proto_timing.h File Reference

Physical-layer radio and timing parameters for the IO-Homecontrol protocol. More...

#include <cstdint>

Include dependency graph for proto_timing.h:

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

Go to the source code of this file.

Namespaces
namespace	esphome
namespace	esphome::home_io_control

Enumerations
enum class	esphome::home_io_control::TxWake : uint8_t { esphome::home_io_control::NONE , esphome::home_io_control::SHORT , esphome::home_io_control::LONG }
	How hard a transmission has to work to be heard: the wake-up level the receiver needs. More...

Functions
constexpr bool	esphome::home_io_control::is_wake_preamble (uint16_t len)
	True when a preamble this long is the wake-up burst for a duty-cycled receiver.
constexpr TxWake	esphome::home_io_control::tx_wake_for (bool start, uint16_t preamble)
	The wake-up level of a frame, from the two facts that decide it: whether it starts an exchange (a continuation reaches a receiver that is already listening) and whether its preamble is the wake-up burst.

Variables
static constexpr uint32_t	esphome::home_io_control::FREQ_CH1 = 868250000
	The protocol uses 3 frequency channels in the 868 MHz ISM band.
static constexpr uint32_t	esphome::home_io_control::FREQ_CH2 = 868950000
	Channel 2: 868.95 MHz (1W and 2W, TX channel).
static constexpr uint32_t	esphome::home_io_control::FREQ_CH3 = 869850000
	Channel 3: 869.85 MHz (2W only).
static constexpr uint32_t	esphome::home_io_control::DISCOVERY_SLOT_MS = 41
	Length of one discovery answer slot.
static constexpr uint16_t	esphome::home_io_control::LONG_PREAMBLE = 1024
	Preamble is a sequence of 0xAA bytes that precedes every frame.
static constexpr uint16_t	esphome::home_io_control::SHORT_PREAMBLE = 8
	Protocol default and floor for continuation frames.
static constexpr uint16_t	esphome::home_io_control::COLD_BROADCAST_REPLY_PREAMBLE = 80
	Default for TuningConfig::cold_broadcast_reply_preamble — preamble for a broadcast reply to a frame the peer caught via a rotating/hopping listen (currently: only the key-extraction responder's 0x29, the sole start=true frame any device-role builder in this codebase produces) — long enough to be reliably caught by a hopping receiver, short enough that sending it doesn't block the loop the way LONG_PREAMBLE does.
static constexpr uint16_t	esphome::home_io_control::NORMAL_START_PREAMBLE = 32
	Default for TuningConfig::normal_start_preamble — the preamble in front of a directed start frame whose target is not a low-power / duty-cycled device (CTRL1_LOW_POWER clear).
static constexpr uint32_t	esphome::home_io_control::PREAMBLE_LINGER_DWELL_MS = 15
	Preamble/sync linger extension for a rotating listen (ListenSpec::linger_dwell_ms): how much longer to stay on a channel once a frame is visibly incoming, so a hop doesn't cut it off mid-reception.
static constexpr uint32_t	esphome::home_io_control::SESSION_HOLD_BASE_MS = 35
	Base of how long a node acting as a device holds the session's channel after answering a controller, before it scans all channels again.
static constexpr int32_t	esphome::home_io_control::HOP_TIME_US = 2700
	Timing constants for frequency hopping and response waiting.
static constexpr int32_t	esphome::home_io_control::RESPONSE_WAIT_MS = 500
	Wait for response to non-start frame.
static constexpr int32_t	esphome::home_io_control::RESPONSE_START_WAIT_MS = 400
	Wait for a response to a start frame — the first frame of an exchange, and the one a sleeping device has just been woken by.
static constexpr int32_t	esphome::home_io_control::RESPONSE_AUTH_WAIT_MS
	Wait for final response after challenge response.
static constexpr int32_t	esphome::home_io_control::EXCHANGE_RETRY_DELAY_MS = 250
	Gap between retries within one HA command.
static constexpr uint8_t	esphome::home_io_control::EXCHANGE_RETRY_COUNT = 3
	Attempts per exchange for every caller that has not asked for an attempt plan (decisions::attempt_plan()): a command that is not repeat-safe (decisions::is_repeat_safe_command()), heater registers, management actions and the pairing loops.
static constexpr uint8_t	esphome::home_io_control::EXCHANGE_MAX_ATTEMPTS = 9
	Most attempts any exchange makes, whatever the budget allows: a plan with a long exchange_total_budget_ms still stops here, so a dead device is not hammered with 25 copies of a read.
static constexpr uint8_t	esphome::home_io_control::LOW_POWER_SETTLING_ATTEMPTS = 3
	Attempts a settling read makes to a low-power receiver.
static constexpr uint16_t	esphome::home_io_control::LOW_POWER_SHORT_LEAD_WINDOW_MS = 100
	How long the short lead attempt of a read to a low-power receiver in an unknown state listens after the end of its own transmission (decisions::WakeBelief::UNKNOWN, ADR 0079).
static constexpr uint16_t	esphome::home_io_control::LOW_POWER_RESPONSE_WAIT_MS = 550
	How long a read listens for a low-power receiver's reply after the end of its own transmission, on every attempt.
static constexpr uint16_t	esphome::home_io_control::EXCHANGE_EARLY_RESPONSE_WAIT_MS = 200
	How long an attempt listens for a mains device's reply when another attempt follows it, after the end of its own transmission.
static constexpr uint32_t	esphome::home_io_control::EXCHANGE_ATTEMPT_OVERHEAD_MS = 10
	Time an attempt costs beyond its transmission and its listen: the channel-busy check, the frequency hop and the SPI traffic around each transmit.
static constexpr uint8_t	esphome::home_io_control::UNCONFIRMED_EXECUTE_MAX_RESENDS = 1
	Re-sends allowed for a CMD_EXECUTE the target accepted without a closing reply, within the same exchange and its retry budget.
static constexpr uint8_t	esphome::home_io_control::UNCONFIRMED_SUBSCRIBE_MAX_RESENDS = 1
	Re-sends allowed for a CMD_SUBSCRIBE_EVENT the target accepted without a closing reply.
static constexpr uint32_t	esphome::home_io_control::UNCONFIRMED_EXECUTE_RESEND_DELAY_MS = 750
	Gap before that re-send, in place of the plan's retry gap (decisions::AttemptPlan::gap_ms).
static constexpr uint32_t	esphome::home_io_control::LOW_POWER_MAX_TRAVEL_MS = 120000
	How long evidence that a low-power receiver is moving keeps it believed awake enough to hear the short start preamble first.
static constexpr uint8_t	esphome::home_io_control::PAIRING_SET_CONFIG1_MAX_TRIES = 1
	Tries for pairing's phase-3 SetConfig1 (0x6F).
static constexpr uint8_t	esphome::home_io_control::SCHEDULED_POLL_MAX_TRIES = 1
	Exchange tries for a status poll the scheduler owns that only looks at a device that is probably still busy: every poll of a tracked device that is not a settling read (decisions::scheduled_poll_read_kind()).
static constexpr uint8_t	esphome::home_io_control::SCHEDULED_POLL_RETRY_GRACE_FIRST_FAILURE = 1
	Ladder positions at which a scheduler-owned status poll is a settling read again.
static constexpr uint8_t	esphome::home_io_control::SCHEDULED_POLL_RETRY_GRACE_LAST_FAILURE = 3
static constexpr uint32_t	esphome::home_io_control::REMOTE_ACTIVITY_STATUS_POLL_DELAY_MS = 2000
	Delay before polling after overheard remote traffic: another controller's frame to a registered device, and, by default, a linked-remote press (its remote_activity_poll_delay_ms tuning default; ADR 0080).
static constexpr uint16_t	esphome::home_io_control::EXCHANGE_TOTAL_BUDGET_MS = 2500
	Wall-clock ceiling on one whole exchange, retries included.
static constexpr uint8_t	esphome::home_io_control::ONEWAY_BURST_REPEATS = 4
	One-way (1W) transmit cadence.
static constexpr uint32_t	esphome::home_io_control::ONEWAY_BURST_INTERVAL_MS = 40
	Gap between those copies.
static constexpr uint32_t	esphome::home_io_control::RAIN_EVIDENCE_HOLD_MS = 2UL * 60UL * 60UL * 1000UL
	How long a status reply that named the rain sensor as the last commander stays usable as evidence that rain protection is active (see decisions::is_rain_limited(), rule b).
static constexpr int16_t	esphome::home_io_control::LBT_RSSI_THRESHOLD_DBM = -90
	Listen-before-talk (LBT) parameters: conservative defaults that keep the hub from opening an exchange over traffic it can hear.
static constexpr uint8_t	esphome::home_io_control::LBT_MAX_RETRIES = 5
	Max carrier-sense attempts before TX anyway.
static constexpr uint8_t	esphome::home_io_control::LBT_RETRY_DELAY_MS = 5
	Backoff between LBT checks.
static constexpr uint16_t	esphome::home_io_control::PAIRING_DISCOVERY_WAIT_MS = 2000
	Canonical defaults for the chip-neutral runtime-tunable pairing/discovery parameters.
static constexpr uint16_t	esphome::home_io_control::PAIRING_DISCOVERY_INITIAL_DWELL_MS = 300
	Dwell on CH2 before discovery hopping begins.
static constexpr uint8_t	esphome::home_io_control::PAIRING_KEY_EXCHANGE_RETRIES = 3
	Retries for the authenticated key-exchange phase.
static constexpr uint16_t	esphome::home_io_control::PAIRING_KEY_INIT_DELAY_MS = 300
	Default for TuningConfig::pairing_key_init_delay_ms — pause after the discover-confirm step (whether it was ACKed, refused, or silent) and before CMD_KEY_INIT (0x31).

Detailed Description

Physical-layer radio and timing parameters for the IO-Homecontrol protocol.

Definition in file proto_timing.h.