All runtime tunable parameters for pairing and radio diagnostics. More...

#include <tuning_config.h>

Collaboration diagram for esphome::home_io_control::TuningConfig:

Public Attributes
SX1262RxBandwidth	sx1262_rx_bandwidth {SX1262RxBandwidth::BW_58_6_KHZ}
	SX1262 RX bandwidth selector.
uint16_t	sx1262_response_preamble {SX1262_RESPONSE_PREAMBLE}
	SX1262 response preamble in bytes.
uint16_t	sx1262_post_tx_settle_us {SX1262_POST_TX_SETTLE_US}
	Delay after SX1262 TX before RX (µs).
SX1276RxBandwidth	sx1276_rx_bandwidth {SX1276RxBandwidth::BW_41_7_KHZ}
	SX1276 RX bandwidth selector.
uint16_t	sx1276_response_preamble {SX1276_RESPONSE_PREAMBLE}
	SX1276 response preamble in bytes.
uint16_t	sx1276_discovery_hop_slice_ms
	Per-channel dwell while SX1276 discovery hops.
uint16_t	sx1262_discovery_hop_slice_ms
	Per-channel dwell while SX1262 discovery hops.
LR1121RxBandwidth	lr1121_rx_bandwidth {LR1121RxBandwidth::BW_117_3_KHZ}
	LR1121 RX bandwidth selector.
uint16_t	lr1121_response_preamble {LR1121_RESPONSE_PREAMBLE}
	LR1121 response preamble in bytes.
uint16_t	lr1121_post_tx_settle_us {LR1121_POST_TX_SETTLE_US}
	Delay after LR1121 TX before RX (µs).
uint16_t	lr1121_discovery_hop_slice_ms
	Per-channel dwell while LR1121 discovery hops.
uint16_t	cold_broadcast_reply_preamble
	Preamble for a start-flagged key-extraction broadcast reply (0x29).
uint16_t	key_extraction_type_word
	Packed type word the key-extraction 0x29 advertises to an open discovery (type << 6 \| subtype).
uint8_t	key_extraction_multi_info
	Multi Information Byte the key-extraction 0x29 advertises.
uint16_t	normal_start_preamble
	Preamble for a directed start frame to a non-low-power target.
bool	normal_start_preamble_from_yaml {false}
	True when normal_start_preamble: appeared in YAML.
uint8_t	lbt_max_retries {LBT_MAX_RETRIES}
	LBT retries before forced TX.
int16_t	lbt_rssi_threshold_dbm {LBT_RSSI_THRESHOLD_DBM}
	LBT channel-free threshold (dBm).
bool	low_power_wake_belief {true}
	Order a low_power device's start-frame tries by its wake belief (short preamble first when it is believed awake).
uint16_t	low_power_wake_preamble {LONG_PREAMBLE}
	Wake-up preamble (bytes) on a directed start frame to a low_power target believed at rest.
uint16_t	exchange_start_response_wait_ms
	Reply window for a start frame (wakes a sleeping device).
uint16_t	exchange_early_response_wait_ms {EXCHANGE_EARLY_RESPONSE_WAIT_MS}
	Reply window of every attempt before the last when a mains target is asked more than once (decisions::attempt_plan()); the last attempt listens exchange_start_response_wait_ms.
uint16_t	exchange_response_wait_ms
	Reply window for continuation frames and the post-auth final response.
uint16_t	exchange_total_budget_ms {EXCHANGE_TOTAL_BUDGET_MS}
	Ceiling on one whole exchange, retries included.
uint32_t	remote_activity_poll_delay_ms
	Delay from a linked-remote press (not a STOP) to the first status poll of its devices.
uint32_t	remote_activity_catchup_poll_ms {0}
	Read every linked device this long after the last exchange of a burst of linked-remote activity; 0 = off.
std::vector< DiscoveryCommand >	pairing_discovery_commands
	Ordered discovery commands.
std::vector< uint8_t >	pairing_discovery_destination {0x00, 0x00, 0x00}
	Destination when auto=false.
bool	pairing_discovery_destination_auto {true}
	When true, map commands to conventional addresses.
uint8_t	pairing_discovery_payload {0}
	Optional payload byte (used for 0x2E).
bool	pairing_discovery_payload_enabled {false}
	Whether the optional payload is enabled.
bool	pairing_discovery_low_power {false}
	Set LOW_POWER flag in discovery frames.
bool	pairing_discovery_ack_capable {false}
	Set ACK (CTRL1_ACK) on the discovery broadcast only.
uint16_t	pairing_discovery_preamble {NORMAL_START_PREAMBLE}
	Preamble (bytes) of the discovery broadcast (0x28/0x2E) when the user chose one.
bool	pairing_discovery_preamble_set {false}
	True when pairing_discovery_preamble was set, from YAML or by a write through the Home Assistant number (it stays set until the next restart).
uint16_t	pairing_discovery_wait_ms
	Total wait window after sending discovery commands.
uint16_t	pairing_discovery_initial_dwell_ms
	Initial dwell on CH2 before discovery hopping begins.
uint8_t	pairing_key_exchange_retries
	Retries for the authenticated key exchange phase.
ScanPowerClasses	scan_power_classes
	Power classes the scan_paired_devices roll-call calls.
DiscoverConfirmMode	pairing_discover_confirm
	Whether/how to send CMD_DISCOVER_CONFIRM (0x2C) during pairing.
DiscoveryListenChannels	pairing_discovery_listen_channels
	Channels the discovery response wait covers.
KeyTransferMode	pairing_key_transfer {KeyTransferMode::AUTO}
	Push our key, or pull the device's key.
uint16_t	pairing_key_init_delay_ms
	Pause after the discover-confirm step, before CMD_KEY_INIT (0x31).
bool	active {false}
	True when the YAML tuning: block is present.

Detailed Description

All runtime tunable parameters for pairing and radio diagnostics.

Values reset to their defaults on every boot. Each field initializes from a canonical constant — chip-neutral defaults live in proto_timing.h, chip-specific defaults in this header — shared with the ESPHome YAML schema. The hub stores a single TuningConfig instance and passes it to the radio driver and pairing flow. UI callbacks update the hub instance directly; the snapshot helpers emit the current values in YAML-compatible form so a working combination can be copied back into the configuration file.

Definition at line 267 of file tuning_config.h.

Member Data Documentation

◆ active

bool esphome::home_io_control::TuningConfig::active {false}

True when the YAML tuning: block is present.

Definition at line 376 of file tuning_config.h.

◆ cold_broadcast_reply_preamble

uint16_t esphome::home_io_control::TuningConfig::cold_broadcast_reply_preamble

Initial value:

{

COLD_BROADCAST_REPLY_PREAMBLE}

Preamble for a start-flagged key-extraction broadcast reply (0x29).

Definition at line 291 of file tuning_config.h.

◆ exchange_early_response_wait_ms

uint16_t esphome::home_io_control::TuningConfig::exchange_early_response_wait_ms {EXCHANGE_EARLY_RESPONSE_WAIT_MS}

Reply window of every attempt before the last when a mains target is asked more than once (decisions::attempt_plan()); the last attempt listens exchange_start_response_wait_ms.

A mains device answers within tens of milliseconds or not at all, so a shorter early listen fits more attempts into exchange_total_budget_ms (nine at the default). The default rests on corpus reply latencies and bench measurements, see EXCHANGE_EARLY_RESPONSE_WAIT_MS. A value above the start window is capped to it.

Definition at line 328 of file tuning_config.h.

◆ exchange_response_wait_ms

uint16_t esphome::home_io_control::TuningConfig::exchange_response_wait_ms

Initial value:

{

RESPONSE_WAIT_MS}

Reply window for continuation frames and the post-auth final response.

Definition at line 329 of file tuning_config.h.

◆ exchange_start_response_wait_ms

uint16_t esphome::home_io_control::TuningConfig::exchange_start_response_wait_ms

Initial value:

{

RESPONSE_START_WAIT_MS}

Reply window for a start frame (wakes a sleeping device).

Definition at line 320 of file tuning_config.h.

◆ exchange_total_budget_ms

uint16_t esphome::home_io_control::TuningConfig::exchange_total_budget_ms {EXCHANGE_TOTAL_BUDGET_MS}

Ceiling on one whole exchange, retries included.

Definition at line 331 of file tuning_config.h.

◆ key_extraction_multi_info

uint8_t esphome::home_io_control::TuningConfig::key_extraction_multi_info

Initial value:

{

KEY_EXTRACTION_DISCOVER_RESP_FLAGS}

Multi Information Byte the key-extraction 0x29 advertises.

Definition at line 296 of file tuning_config.h.

◆ key_extraction_type_word

uint16_t esphome::home_io_control::TuningConfig::key_extraction_type_word

Initial value:

{

KEY_EXTRACTION_DISCOVER_RESP_TYPE_WORD}

Packed type word the key-extraction 0x29 advertises to an open discovery (type << 6 | subtype).

Definition at line 293 of file tuning_config.h.

◆ lbt_max_retries

uint8_t esphome::home_io_control::TuningConfig::lbt_max_retries {LBT_MAX_RETRIES}

LBT retries before forced TX.

Definition at line 307 of file tuning_config.h.

◆ lbt_rssi_threshold_dbm

int16_t esphome::home_io_control::TuningConfig::lbt_rssi_threshold_dbm {LBT_RSSI_THRESHOLD_DBM}

LBT channel-free threshold (dBm).

Definition at line 308 of file tuning_config.h.

◆ low_power_wake_belief

bool esphome::home_io_control::TuningConfig::low_power_wake_belief {true}

Order a low_power device's start-frame tries by its wake belief (short preamble first when it is believed awake).

False restores the fixed wake-up preamble on every try. A diagnostic off-switch, on by default.

Definition at line 309 of file tuning_config.h.

◆ low_power_wake_preamble

uint16_t esphome::home_io_control::TuningConfig::low_power_wake_preamble {LONG_PREAMBLE}

Wake-up preamble (bytes) on a directed start frame to a low_power target believed at rest.

Definition at line 312 of file tuning_config.h.

◆ lr1121_discovery_hop_slice_ms

uint16_t esphome::home_io_control::TuningConfig::lr1121_discovery_hop_slice_ms

Initial value:

{

LR1121_DISCOVERY_HOP_SLICE_MS}

Per-channel dwell while LR1121 discovery hops.

Definition at line 289 of file tuning_config.h.

◆ lr1121_post_tx_settle_us

uint16_t esphome::home_io_control::TuningConfig::lr1121_post_tx_settle_us {LR1121_POST_TX_SETTLE_US}

Delay after LR1121 TX before RX (µs).

Definition at line 288 of file tuning_config.h.

◆ lr1121_response_preamble

uint16_t esphome::home_io_control::TuningConfig::lr1121_response_preamble {LR1121_RESPONSE_PREAMBLE}

LR1121 response preamble in bytes.

Definition at line 287 of file tuning_config.h.

◆ lr1121_rx_bandwidth

LR1121RxBandwidth esphome::home_io_control::TuningConfig::lr1121_rx_bandwidth {LR1121RxBandwidth::BW_117_3_KHZ}

LR1121 RX bandwidth selector.

Definition at line 286 of file tuning_config.h.

◆ normal_start_preamble

uint16_t esphome::home_io_control::TuningConfig::normal_start_preamble

Initial value:

{

NORMAL_START_PREAMBLE}

Preamble for a directed start frame to a non-low-power target.

Resolved at setup from RadioDriver::default_start_preamble() unless normal_start_preamble_from_yaml says the user set it.

Definition at line 298 of file tuning_config.h.

◆ normal_start_preamble_from_yaml

bool esphome::home_io_control::TuningConfig::normal_start_preamble_from_yaml {false}

True when normal_start_preamble: appeared in YAML.

Codegen emits this alongside the value; it exists so setup() can tell "the user chose 32" from "nobody chose anything", which decides whether the driver's default applies (ADR 0042). Only read once, at setup — a later change through the Home Assistant number simply sets the value.

Definition at line 306 of file tuning_config.h.

◆ pairing_discover_confirm

DiscoverConfirmMode esphome::home_io_control::TuningConfig::pairing_discover_confirm

Initial value:

{

DiscoverConfirmMode::SEND}

esphome::home_io_control::DiscoverConfirmMode::SEND

@ SEND

Default.

Definition tuning_config.h:105

Whether/how to send CMD_DISCOVER_CONFIRM (0x2C) during pairing.

Definition at line 367 of file tuning_config.h.

◆ pairing_discovery_ack_capable

bool esphome::home_io_control::TuningConfig::pairing_discovery_ack_capable {false}

Set ACK (CTRL1_ACK) on the discovery broadcast only.

Opt-in — see the init_frame() doc in proto_frame.h; default off.

Definition at line 349 of file tuning_config.h.

◆ pairing_discovery_commands

std::vector<DiscoveryCommand> esphome::home_io_control::TuningConfig::pairing_discovery_commands

Initial value:

{

DiscoveryCommand::DISCOVER}

esphome::home_io_control::DiscoveryCommand::DISCOVER

@ DISCOVER

Standard broadcast discovery request (to 0x00003B).

Definition tuning_config.h:159

Ordered discovery commands.

Definition at line 342 of file tuning_config.h.

◆ pairing_discovery_destination

std::vector<uint8_t> esphome::home_io_control::TuningConfig::pairing_discovery_destination {0x00, 0x00, 0x00}

Destination when auto=false.

Definition at line 344 of file tuning_config.h.

◆ pairing_discovery_destination_auto

bool esphome::home_io_control::TuningConfig::pairing_discovery_destination_auto {true}

When true, map commands to conventional addresses.

Definition at line 345 of file tuning_config.h.

◆ pairing_discovery_initial_dwell_ms

uint16_t esphome::home_io_control::TuningConfig::pairing_discovery_initial_dwell_ms

Initial value:

{

PAIRING_DISCOVERY_INITIAL_DWELL_MS}

Initial dwell on CH2 before discovery hopping begins.

Definition at line 361 of file tuning_config.h.

◆ pairing_discovery_listen_channels

DiscoveryListenChannels esphome::home_io_control::TuningConfig::pairing_discovery_listen_channels

Initial value:

{

DiscoveryListenChannels::SKIP_REQUEST}

esphome::home_io_control::DiscoveryListenChannels::SKIP_REQUEST

@ SKIP_REQUEST

Default. The two channels that are not the request channel.

Definition tuning_config.h:131

Channels the discovery response wait covers.

Definition at line 369 of file tuning_config.h.

◆ pairing_discovery_low_power

bool esphome::home_io_control::TuningConfig::pairing_discovery_low_power {false}

Set LOW_POWER flag in discovery frames.

Definition at line 348 of file tuning_config.h.

◆ pairing_discovery_payload

uint8_t esphome::home_io_control::TuningConfig::pairing_discovery_payload {0}

Optional payload byte (used for 0x2E).

Definition at line 346 of file tuning_config.h.

◆ pairing_discovery_payload_enabled

bool esphome::home_io_control::TuningConfig::pairing_discovery_payload_enabled {false}

Whether the optional payload is enabled.

Definition at line 347 of file tuning_config.h.

◆ pairing_discovery_preamble

uint16_t esphome::home_io_control::TuningConfig::pairing_discovery_preamble {NORMAL_START_PREAMBLE}

Preamble (bytes) of the discovery broadcast (0x28/0x2E) when the user chose one.

Read through effective_discovery_preamble(), never directly: it counts only while pairing_discovery_preamble_set is true, otherwise discovery follows the start preamble.

Definition at line 355 of file tuning_config.h.

◆ pairing_discovery_preamble_set

bool esphome::home_io_control::TuningConfig::pairing_discovery_preamble_set {false}

True when pairing_discovery_preamble was set, from YAML or by a write through the Home Assistant number (it stays set until the next restart).

Codegen emits it next to the value.

Definition at line 358 of file tuning_config.h.

◆ pairing_discovery_wait_ms

uint16_t esphome::home_io_control::TuningConfig::pairing_discovery_wait_ms

Initial value:

{

PAIRING_DISCOVERY_WAIT_MS}

Total wait window after sending discovery commands.

Definition at line 359 of file tuning_config.h.

◆ pairing_key_exchange_retries

uint8_t esphome::home_io_control::TuningConfig::pairing_key_exchange_retries

Initial value:

{

PAIRING_KEY_EXCHANGE_RETRIES}

Retries for the authenticated key exchange phase.

Definition at line 363 of file tuning_config.h.

◆ pairing_key_init_delay_ms

uint16_t esphome::home_io_control::TuningConfig::pairing_key_init_delay_ms

Initial value:

{

PAIRING_KEY_INIT_DELAY_MS}

Pause after the discover-confirm step, before CMD_KEY_INIT (0x31).

Definition at line 372 of file tuning_config.h.

◆ pairing_key_transfer

KeyTransferMode esphome::home_io_control::TuningConfig::pairing_key_transfer {KeyTransferMode::AUTO}

Push our key, or pull the device's key.

Definition at line 371 of file tuning_config.h.

◆ remote_activity_catchup_poll_ms

uint32_t esphome::home_io_control::TuningConfig::remote_activity_catchup_poll_ms {0}

Read every linked device this long after the last exchange of a burst of linked-remote activity; 0 = off.

Definition at line 338 of file tuning_config.h.

◆ remote_activity_poll_delay_ms

uint32_t esphome::home_io_control::TuningConfig::remote_activity_poll_delay_ms

Initial value:

{

REMOTE_ACTIVITY_STATUS_POLL_DELAY_MS}

Delay from a linked-remote press (not a STOP) to the first status poll of its devices.

Definition at line 335 of file tuning_config.h.

◆ scan_power_classes

ScanPowerClasses esphome::home_io_control::TuningConfig::scan_power_classes

Initial value:

{

ScanPowerClasses::BOTH}

esphome::home_io_control::ScanPowerClasses::BOTH

@ BOTH

Low-power pass, then always-alive pass (default).

Definition tuning_config.h:90

Power classes the scan_paired_devices roll-call calls.

Definition at line 365 of file tuning_config.h.

◆ sx1262_discovery_hop_slice_ms

uint16_t esphome::home_io_control::TuningConfig::sx1262_discovery_hop_slice_ms

Initial value:

{

SX1262_DISCOVERY_HOP_SLICE_MS}

Per-channel dwell while SX1262 discovery hops.

Definition at line 284 of file tuning_config.h.

◆ sx1262_post_tx_settle_us

uint16_t esphome::home_io_control::TuningConfig::sx1262_post_tx_settle_us {SX1262_POST_TX_SETTLE_US}

Delay after SX1262 TX before RX (µs).

Definition at line 279 of file tuning_config.h.

◆ sx1262_response_preamble

uint16_t esphome::home_io_control::TuningConfig::sx1262_response_preamble {SX1262_RESPONSE_PREAMBLE}

SX1262 response preamble in bytes.

Definition at line 278 of file tuning_config.h.

◆ sx1262_rx_bandwidth

SX1262RxBandwidth esphome::home_io_control::TuningConfig::sx1262_rx_bandwidth {SX1262RxBandwidth::BW_58_6_KHZ}

SX1262 RX bandwidth selector.

58.6 kHz (double-sideband). This is below the 76.8 kHz sizing floor for this waveform (see SX1262RxBandwidth), so it trims the edges of even an on-frequency signal; it is the default because it made a real solar shutter (Somfy RS100) respond reliably where 117.3 kHz did not. Because the SX1262 has no GFSK AFC, a peer whose carrier sits off nominal needs a wider setting instead: a Somfy LightVar_Wh_io dimmer went from mostly missed to mostly confirmed replies at 156.2 kHz. The setting is global, so the right value is a per-install trade-off.

Definition at line 277 of file tuning_config.h.

◆ sx1276_discovery_hop_slice_ms

uint16_t esphome::home_io_control::TuningConfig::sx1276_discovery_hop_slice_ms

Initial value:

{

SX1276_DISCOVERY_HOP_SLICE_MS}

Per-channel dwell while SX1276 discovery hops.

Definition at line 282 of file tuning_config.h.

◆ sx1276_response_preamble

uint16_t esphome::home_io_control::TuningConfig::sx1276_response_preamble {SX1276_RESPONSE_PREAMBLE}

SX1276 response preamble in bytes.

Definition at line 281 of file tuning_config.h.

◆ sx1276_rx_bandwidth

SX1276RxBandwidth esphome::home_io_control::TuningConfig::sx1276_rx_bandwidth {SX1276RxBandwidth::BW_41_7_KHZ}

SX1276 RX bandwidth selector.

Definition at line 280 of file tuning_config.h.

The documentation for this struct was generated from the following file:

components/home_io_control/tuning_config.h

Public Attributes

Detailed Description

Member Data Documentation

◆ active

◆ cold_broadcast_reply_preamble

◆ exchange_early_response_wait_ms

◆ exchange_response_wait_ms

◆ exchange_start_response_wait_ms

◆ exchange_total_budget_ms

◆ key_extraction_multi_info

◆ key_extraction_type_word

◆ lbt_max_retries

◆ lbt_rssi_threshold_dbm

◆ low_power_wake_belief

◆ low_power_wake_preamble

◆ lr1121_discovery_hop_slice_ms

◆ lr1121_post_tx_settle_us

◆ lr1121_response_preamble

◆ lr1121_rx_bandwidth

◆ normal_start_preamble

◆ normal_start_preamble_from_yaml

◆ pairing_discover_confirm

◆ pairing_discovery_ack_capable

◆ pairing_discovery_commands

◆ pairing_discovery_destination

◆ pairing_discovery_destination_auto

◆ pairing_discovery_initial_dwell_ms

◆ pairing_discovery_listen_channels

◆ pairing_discovery_low_power

◆ pairing_discovery_payload

◆ pairing_discovery_payload_enabled

◆ pairing_discovery_preamble

◆ pairing_discovery_preamble_set

◆ pairing_discovery_wait_ms

◆ pairing_key_exchange_retries

◆ pairing_key_init_delay_ms

◆ pairing_key_transfer

◆ remote_activity_catchup_poll_ms

◆ remote_activity_poll_delay_ms

◆ scan_power_classes

◆ sx1262_discovery_hop_slice_ms

◆ sx1262_post_tx_settle_us

◆ sx1262_response_preamble

◆ sx1262_rx_bandwidth

◆ sx1276_discovery_hop_slice_ms

◆ sx1276_response_preamble

◆ sx1276_rx_bandwidth