esphome::home_io_control Namespace Reference

Namespaces
namespace	decisions
namespace	exchange
namespace	detail
namespace	pairing
namespace	advisor
namespace	pairing_responder
namespace	crypto

Classes
struct	DeviceConfig
	YAML-declared device metadata for registration; defaults match an undeclared device. More...
class	DeviceRegistry
	Owns the per-hub device table, update callbacks, and linked-remote associations. More...
class	ExchangeEngine
class	IOHomeControlComponent
	The main IO-Homecontrol component. More...
struct	ListenSpec
	How one listen window is to be spent — everything ExchangeEngine::listen() needs; everything else is the handler's business. More...
class	KeyExtractionResponder
	Device-role responder for the "Recover System Key" feature. More...
struct	Lr1121BootloaderRequirement
	One (target firmware, required bootloader) pairing from Semtech's published compatibility matrix. More...
struct	HeatingNamedValue
	A value token that maps to a fixed float (used by set_mode / set_presence / set_window). More...
struct	ManagementActionResult
	Result of a hub-level management action such as rename. More...
class	ManagementActions
	Encapsulates hub-level management operations exposed as Home Assistant actions. More...
struct	OneWayControllerIdentity
	One configured 1W controller identity. More...
struct	OneWayWireProfile
	Vendor-divergent 1W wire settings for a controller identity. More...
struct	OneWayActionEncoding
	How a OneWayButtonAction reaches the wire. More...
class	OneWayControllerRegistry
	The configured 1W controller identities, in YAML declaration order. More...
class	OnewayKeyAdoption
	Opt-in, receive-only listener that adopts an overheard 1W controller key. More...
class	OneWaySequenceStore
	Per-controller-identity rolling sequence counters, persisted across reboots. More...
struct	OneWayCommandReport
	What a 1W command attempt did — the only feedback this feature can ever produce. More...
class	OneWayTransmitter
	Sends 1W commands as the repeated bursts real remotes send. More...
struct	PendingOperation
	A single queued operation to be dispatched from loop(). More...
class	OperationQueue
	Serialized pending-operation queue with coalescing, deduplication, and two-band ordering. More...
class	PairingEngine
	Owns and drives all three phases of the IO-Homecontrol device pairing flow. More...
struct	PairingTelemetryEvent
	One recorded telemetry event. More...
struct	RecentOneWayPairingSighting
	A 1W pairing-gesture frame observed on the hub's normal passive RX path, remembered so a fresh discover_and_pair() attempt can seed its telemetry with it (issue #27/#65: the discovery telemetry window only starts recording at PairingTelemetry::begin(), so a PROG press completed just before "Discover & Pair" is pressed could otherwise be invisible to the pairing advisor even though the radio heard it just fine). More...
class	PairingTelemetry
	Fixed-size per-attempt telemetry recorder for the pairing flow. More...
class	IOHomeClimate
	Climate entity for IO-Homecontrol heating devices. More...
class	IOHomeRssiSensor
	Diagnostic sensor that publishes a device's smoothed (EMA) RSSI in dBm. More...
class	IOHomeLastContactSensor
	Diagnostic sensor that publishes seconds elapsed since the last frame received from a device (see detail::update_link_health() in hub_internal.h). More...
class	IOHomeExchangeFailuresSensor
	Diagnostic sensor that publishes a device's cumulative count of outbound exchanges that timed out (no valid response) — see detail::record_exchange_timeout() in hub_internal.h. More...
class	IOHomeDeviceNameTextSensor
	Diagnostic text sensor that publishes the cached device name. More...
class	IOHomeActiveIssueTextSensor
	Diagnostic text sensor that publishes the symbolic name of a device's most recent CMD_ERROR_RESP result code (e.g. More...
class	IOHomeLastCommandedByTextSensor
	Diagnostic text sensor naming the controller that last commanded this device. More...
class	IOHomeLastCommandSourceTextSensor
	Diagnostic text sensor naming what kind of source issued that last command. More...
class	IOHomeCover
	Cover entity representing an IO‑Homecontrol shutter/awning/blind. More...
class	IOHomeCoverCommandButton
	Button entity that sends one non-positional cover command on press. More...
class	IOHomeCoverSilentSwitch
	Switch entity that selects a cover's travel profile at runtime. More...
class	DeviceBoundEntity
	Mixin holding the hub-device binding shared by all IO-Homecontrol entity platforms. More...
class	DeviceBoundCompanion
	Mixin holding the parent + device-id binding shared by per-device entities that are not full entity platforms: the auto-generated companion diagnostic sensors (device name, active issue, RSSI, last contact, exchange failures, last commanded by, last command source) and the per-device auxiliary control entities (cover favorite/vent buttons, cover silent switch). More...
class	HubBoundEntity
	Mixin for entities bound to the hub itself rather than to one device. More...
class	OneWayControllerBound
	Mixin for the hub-level entities that additionally scope themselves to one oneway_controllers: identity: the 1W command buttons, the 1W enrollment button, and the per-identity "Last 1W Command" text sensor. More...
class	HubArmingSwitch
	Shared body for the hub-level arming switches. More...
class	IOHomeAcceptForeignPairingSwitch
	Hub-level switch entity: ON arms the key-extraction responder for 10 minutes, OFF disarms it immediately. More...
class	IOHomeRecoverOneWayKeySwitch
	Hub-level switch entity: ON arms the 1W key-recovery listener, OFF disarms it immediately. More...
class	IOHomeDiscoverButton
	Button entity that triggers device discovery and pairing when pressed in Home Assistant. More...
class	IOHomeScanPairedDevicesButton
	Button entity that runs the scan_paired_devices roll-call when pressed. More...
class	IOHomePairingResultTextSensor
	Diagnostic text sensor that publishes PairingTelemetry::result_sensor_string() after every pairing attempt. More...
class	IOHomeLight
	Binary or dimmable light entity for IO‑Homecontrol devices. More...
class	IOHomeLock
	Lock entity for IO-Homecontrol lock devices. More...
class	IOHomeOneWayCommandButton
	Button entity that sends one 1W command as a configured controller identity. More...
class	IOHomeOneWayEnrollButton
	Button entity that registers a configured controller identity as a 1W controller. More...
class	IOHomeOneWayLastCommandTextSensor
	Diagnostic text sensor: what this identity last put on air. More...
class	IOHomeSwitch
	Binary switch entity for IO‑Homecontrol on/off devices. More...
struct	OneWayFrameInfo
	Decoded representation of a 1W remote frame. More...
struct	DiscoveryResponseInfo
	Extended discovery-response fields (manufacturer, Multi Information Byte, backbone address, timestamp) plus flags recording how much of the payload was actually present. More...
struct	OneWayAdoptedKey
	Recovered controller identity from a decoded CMD_ONEWAY_ADD_CONTROLLER (0x30) frame. More...
struct	OptimisticState
	What the hub predicted ahead of confirmation, kept apart from what the device reported. More...
struct	IoDevice
	Runtime state of a paired IO‑Homecontrol device. More...
struct	IoFrame
	Parsed IO‑Homecontrol frame (CTRL0/1 + addresses + command + data). More...
class	SpiAccess
	Interface for SPI bus access. More...
struct	RadioTxConfig
	Configuration for transmitting a packet: carrier frequency and preamble length. More...
struct	RadioRxPacket
	Raw packet received from the radio. More...
struct	RadioCaptureInfo
	Diagnostic capture from a radio operation. More...
class	RadioDriver
	Abstract radio driver for IO-Homecontrol. More...
class	RadioLR1121
	LR1121 implementation of RadioDriver. More...
struct	UartProbeResult
	Result of the UART probe: best candidate frame within a raw capture. More...
class	SoftPhyDriverBase
	Shared RX/TX driver flow for the software-PHY radios (SX1262, LR1121). More...
class	RadioSX1262
	SX1262 implementation of RadioDriver. More...
class	RadioSX1276
	SX1276 implementation of RadioDriver. More...
struct	PollTracking
	Per-device poll scheduling state. More...
class	StatusPollPolicy
	Per-hub poll scheduling and failure-backoff policy. More...
struct	TuningConfig
	All runtime tunable parameters for pairing and radio diagnostics. More...
struct	BandwidthOption
	One selectable RX bandwidth: the chip's register byte and its nominal kHz value. More...
struct	BandwidthTableView
	A pointer/size view over one chip's RX-bandwidth option table. More...
class	IOHomeTuningNumber
	Runtime-tunable number entity. More...
class	IOHomeTuningSelect
	Runtime-tunable select entity. More...
struct	TuningNumberParam
	One numeric tuning parameter: its wire name plus accessors over TuningConfig. More...
struct	TuningSelectParam
	One select tuning parameter: its wire name plus string accessors over TuningConfig. More...

Typedefs
using	DeviceUpdateCallback = std::function<void(const std::string &device_id, const IoDevice &device)>
	Callback type invoked when a device's state changes.
using	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.
using	NamedTimeoutFn = std::function<void(const char *name, uint32_t delay_ms, std::function<void()> callback)>
	Schedules a named, replace-on-same-name timeout on the hub's ESPHome scheduler.
using	TransmitFrameFn = std::function<bool(const IoFrame &frame, uint32_t freq_hz, uint16_t preamble)>
	Puts a frame on air on a given channel via the hub's protected transmit_frame_().
using	BeginBlockingExcursionFn = std::function<void()>
	Raises the hub's "operation took a long time" warning threshold for a blocking radio excursion — writes Component::warn_if_blocking_over_, which is protected on ESPHome's Component.
using	OneWayTransmitFn = std::function<bool(const IoFrame &frame, uint32_t freq, uint16_t preamble)>
	How the transmitter puts a frame on air.
using	OneWayCommandReportFn = std::function<void(const OneWayCommandReport &report)>
	Invoked once per attempted 1W command, successful or not.

Enumerations
enum class	ExchangeOutcome : uint8_t { FAILED , SUCCESS_WITH_RESPONSE , SUCCESS_UNCONFIRMED }
	Authenticated exchange engine — outbound and inbound protocol flows. More...
enum class	ListenPolicy : uint8_t { HOLD_REQUEST_CHANNEL , ROTATE_ALL_CHANNELS , ROTATE_SKIPPING_REQUEST }
	Which channels a listen covers. More...
enum class	ReplyDisposition : uint8_t { ACCEPT , IGNORE , ABORT }
	What the caller wants done with the frame a listen just received. More...
enum class	ListenOutcome : uint8_t { ACCEPTED , ABORTED , TIMED_OUT }
	How one call to ExchangeEngine::listen() ended. More...
enum class	BootloaderSupport : uint8_t { SUPPORTED , UNSUPPORTED , UNKNOWN_TARGET }
	Whether a target firmware version is known to work with a given bootloader version. More...
enum class	BootloaderMismatch : uint8_t { NONE , TARGET_NEEDS_NEWER , TARGET_NEEDS_OLDER }
	Direction of a bootloader/target mismatch, for messaging. More...
enum class	BootloaderUpgradePath : uint8_t { NOT_APPLICABLE , AVAILABLE , BLOCKED_UNKNOWN_TARGET , BLOCKED_BOOTLOADER_NEWER }
	Whether the three-stage bootloader-rewrite sequence (ADR 0021) is applicable, and if not, why. More...
enum class	FlashDecision : uint8_t {   PROCEED , ALREADY_INSTALLED , NEEDS_CONFIRMATION , REJECT_WRONG_CHIP ,   REJECT_BOOTLOADER_TOO_OLD }
	Outcome of lr1121_flash_decision(). More...
enum class	ScanAddResult : uint8_t { ADDED , DUPLICATE , FULL }
	Outcome of add_scan_responder(), so callers can tell a harmless repeat from real loss. More...
enum class	EnrollGesture : uint8_t { SOMFY , VELUX_KLI }
	Which 1W enrollment gesture a manufacturer's actuators expect. More...
enum class	OneWayButtonAction : uint8_t {   OneWayButtonAction::OPEN , OneWayButtonAction::CLOSE , OneWayButtonAction::STOP , OneWayButtonAction::VENT ,   OneWayButtonAction::FAVORITE }
	The command a generated 1W button sends. More...
enum class	PendingOperationType : uint8_t {   SET_POSITION , SET_TILT , SET_POSITION_AND_TILT , DEVICE_COMMAND ,   SET_LIGHT_STATE , SET_LOCK_STATE , SET_SWITCH_STATE , ONEWAY_COMMAND ,   ONEWAY_POSITION , ONEWAY_ENROLL , ONEWAY_UNENROLL , REQUEST_STATUS ,   REQUEST_NAME , DISCOVER_AND_PAIR }
	Discriminator for entries in the pending-operation deque. More...
enum class	PairingTelemetryEventKind : uint8_t {   TX , RX , RX_REJECT , LBT_DEFER ,   PHASE }
	Kind of a recorded telemetry event. More...
enum class	PairingOutcome : uint8_t {   NONE , PAIRED , NO_RESPONSE , INVALID_RESPONSE ,   KEY_EXCHANGE_FAILED , CONFIG_FAILED }
	Final disposition of a pairing attempt, used by the result sensor string. More...
enum class	DeviceNameValidationError : uint8_t {   NONE = 0x00 , EMPTY = 0x01 , TOO_LONG = 0x02 , INVALID_UTF8 = 0x03 ,   UNSUPPORTED_CHAR = 0x04 }
	Validation result for outbound device-name writes. More...
enum class	AddressClass : uint8_t {   UNICAST = 0 , BROADCAST_ALL , BROADCAST_TYPE , DISCOVERY ,   UNKNOWN_BROADCAST }
	Address classification categories for diagnostic purposes. More...
enum class	OneWayMacStatus : uint8_t { NOT_PRESENT = 0 , VERIFIED = 1 , FAILED = 2 }
	Outcome of checking the out-of-length MAC trailer (IoFrame::has_mac) on a decoded CMD_ONEWAY_ADD_CONTROLLER frame. More...
enum class	OneWayAddControllerDecodeError : uint8_t {   NONE = 0 , NOT_ONEWAY = 1 , WRONG_COMMAND = 2 , BAD_LENGTH = 3 ,   KEY_UNWRAP_FAILED = 4 }
	Decoding outcome for decode_1w_add_controller(). More...
enum class	DeviceType : uint8_t {   UNKNOWN = 0x00 , VENETIAN_BLIND = 0x01 , ROLLER_SHUTTER = 0x02 , AWNING = 0x03 ,   WINDOW_OPENER = 0x04 , GARAGE_OPENER = 0x05 , LIGHT = 0x06 , GATE_OPENER = 0x07 ,   ROLLING_DOOR_OPENER = 0x08 , LOCK = 0x09 , BLIND = 0x0A , SCREEN = 0x0B ,   BEACON = 0x0C , DUAL_SHUTTER = 0x0D , HEATING_TEMPERATURE_INTERFACE = 0x0E , ON_OFF_SWITCH = 0x0F ,   HORIZONTAL_AWNING = 0x10 , EXTERNAL_VENETIAN_BLIND = 0x11 , LOUVRE_BLIND = 0x12 , CURTAIN_TRACK = 0x13 ,   VENTILATION_POINT = 0x14 , EXTERIOR_HEATING = 0x15 , HEAT_PUMP = 0x16 , INTRUSION_ALARM = 0x17 ,   SWINGING_SHUTTER = 0x18 }
	Device type identifiers reported by IO‑Homecontrol products. More...
enum class	DeviceCapabilityClass : uint8_t {   UNKNOWN = 0x00 , COVER = 0x01 , LIGHT = 0x02 , SWITCH = 0x03 ,   SENSOR = 0x04 , BEACON = 0x05 , CLIMATE = 0x06 , LOCK = 0x07 }
	High‑level capability class derived from DeviceType. More...
enum class	CoverCommand : uint8_t { STOP = 0 , FAVORITE = 1 , VENT = 2 , FORCE_OPEN = 3 }
	Named device commands for cover-type actuators. More...
enum class	HeatingFunction : uint8_t {   POWER_ON , SET_TEMPERATURE , SET_MODE , SET_PRESENCE ,   SET_WINDOW , MIDNIGHT_SYNC }
	Heating functions, one per user-pressable radiator button in the reference. More...
enum class	HeatingMode : uint8_t { AUTO = 0x00 , MANUAL = 0x01 , PROG = 0x02 , OFF = 0x04 }
	Operating modes for HeatingFunction::SET_MODE. More...
enum class	SX1262RxBandwidth : uint8_t {   BW_39_0_KHZ = 0x1C , BW_46_9_KHZ = 0x14 , BW_58_6_KHZ = 0x0C , BW_78_2_KHZ = 0x1B ,   BW_117_3_KHZ = 0x0B , BW_156_2_KHZ = 0x1A , BW_187_2_KHZ = 0x12 }
	Valid SX1262 RX bandwidth options (kHz register values). More...
enum class	SX1276RxBandwidth : uint8_t {   BW_20_8_KHZ = 0x14 , BW_41_7_KHZ = 0x13 , BW_62_5_KHZ = 0x03 , BW_83_3_KHZ = 0x12 ,   BW_125_0_KHZ = 0x02 }
	Valid SX1276 RX bandwidth options (RegRxBw register bytes). More...
enum class	LR1121RxBandwidth : uint8_t {   BW_39_0_KHZ = 0x1C , BW_46_9_KHZ = 0x14 , BW_58_6_KHZ = 0x0C , BW_78_2_KHZ = 0x1B ,   BW_117_3_KHZ = 0x0B , BW_156_2_KHZ = 0x1A , BW_187_2_KHZ = 0x12 }
	Valid LR1121 RX bandwidth options (register values). More...
enum class	DiscoveryCommand : uint8_t { DISCOVER = 0x28 , DISCOVER_SPE = 0x2A , DISCOVER_ALT = 0x2E }
	Discovery request command codes. More...

Functions
bool	stored_node_id_is_valid (const uint8_t id[NODE_ID_SIZE])
	Check if a stored node ID is valid (not all-zero, not all-0xFF).
std::string	format_position (float pos)
	Format a position float as a human‑readable string (e.g.
const char *	pairing_stage_name (pairing::PairingState state)
	Get a short, log/telemetry-friendly name for a pairing state.
void	bytes_to_hex (const uint8_t *data, uint8_t len, char *out, size_t out_size)
void	decode_ctrl1_flags (uint8_t ctrl1, char *out, size_t out_size)
	Render decoded CTRL1 flags into a short annotation string.
void	render_frame_hex_redacted (const uint8_t *data, uint8_t len, char *out, size_t out_size)
	Render a frame's bytes as spaced hex text, masking the payload when the command carries key material (see command_carries_key_material()).
constexpr bool	lr1121_bootloader_is_lr1121 (uint16_t bootloader_version)
constexpr const char *	lr1121_chip_family_for_bootloader (uint16_t bootloader_version)
	Human-readable chip family for a bootloader version that is not one of the two LR1121 values above, for an actionable REJECT_WRONG_CHIP message.
constexpr const char *	lr1121_chip_family_for_device_type (uint8_t device_type)
	Human-readable chip family for a normal-mode device_type that is not the LR1121 value above, for an actionable REJECT_WRONG_CHIP message (the layer-3 counterpart of lr1121_chip_family_for_bootloader() above).
constexpr BootloaderSupport	lr1121_bootloader_supports_target (uint16_t target_fw, uint16_t bootloader_version)
	Look up whether target_fw is known to require bootloader_version.
constexpr uint16_t	lr1121_required_bootloader_for (uint16_t target_fw)
	Required bootloader for a known target firmware version.
constexpr BootloaderMismatch	lr1121_bootloader_mismatch_kind (uint16_t target_fw, uint16_t bootloader_version)
	Classify a bootloader/target mismatch by direction; see BootloaderMismatch.
constexpr BootloaderUpgradePath	lr1121_bootloader_upgrade_path (bool block_present, bool bootloader_version_known, uint16_t bootloader_version, uint16_t loader_fw, uint16_t target_fw)
	Whether the three-stage bootloader upgrade is applicable for the current cached state.
constexpr FlashDecision	lr1121_flash_decision (uint8_t device_type, uint8_t bootloader_chip_type, uint16_t bootloader_version, uint16_t installed_fw, uint16_t target_fw, bool already_confirmed)
	The single decision point for whether/how to flash target_fw.
static std::string	normalize_device_id_argument (const std::string &device_id)
static std::string	bool_to_string (bool value)
static std::string	format_hex_byte (uint8_t value)
	Format a byte as two uppercase hex digits, no prefix.
static ManagementActionResult	make_management_result (const std::string &action, const std::string &device_id)
static bool	apply_error_response (const IoFrame &response, ManagementActionResult &result)
	Decode a CMD_ERROR_RESP frame's result code into result.
static bool	parse_probe_index (const std::string &text, uint8_t &out)
	Parse a probe_device()/probe_sweep() index argument into a byte.
static std::string	normalize_lower_argument (const std::string &value)
	Lowercase + ASCII-trim a native-API string argument.
static bool	match_heating_named_value (const std::string &token, const HeatingNamedValue *table, size_t table_len, float &out)
	Match token against table; on a hit set out and return true.
static bool	parse_heating_temperature (const std::string &value, float &value_out, std::string &error)
	Parse set_temperature's value into degrees Celsius, range-checked.
static bool	parse_heating_arguments (const std::string &function, const std::string &value, HeatingFunction &fn_out, float &value_out, std::string &error)
	Parse the (function, value) argument pair of the heating_control action.
static std::string	format_scan_reply_line (const ScanResponder &responder, const std::string &device_id, bool known)
	Format one roll-call responder's report line(s).
static ScanAddResult	add_scan_responder (ScanResponder *responders, uint8_t &count, uint8_t capacity, const IoFrame &frame, int16_t rssi_dbm)
	Record a responder unless its address is already present.
const char *	oneway_button_action_name (OneWayButtonAction action)
	Human-readable name for a button action, as it appears in the diagnostic sensor.
OneWayWireProfile	resolve_oneway_wire_profile (uint8_t manufacturer)
	Resolve an identity's 1W wire profile from its manufacturer byte.
std::array< DeviceType, 3 >	effective_enrollment_classes (const OneWayControllerIdentity &identity)
	The device classes this identity's 0x30 enrollment sweep will actually target.
uint8_t	effective_execute_acei (const OneWayControllerIdentity &identity)
	The ACEI byte a given identity will put on air for a 1W EXECUTE frame.
bool	has_execute_acei_override (const OneWayControllerIdentity &identity)
	Whether this identity's ACEI comes from an explicit execute_acei: rather than the profile.
OneWayActionEncoding	encode_oneway_action (OneWayButtonAction action)
	Resolve a button action to the call that sends it.
std::string	format_oneway_command_report (const OneWayCommandReport &report)
	Build the sensor string for one command report.
std::string	trim_ascii_whitespace (const std::string &value)
	Trim leading and trailing ASCII whitespace from a string.
std::string	decode_device_name_payload (const uint8_t *data, uint8_t len)
	Decode a device-name payload from IO-homecontrol's Latin-1 wire format into UTF-8.
DeviceNameValidationError	encode_device_name_payload (const std::string &name, uint8_t payload[DEVICE_NAME_WRITE_PAYLOAD_SIZE], std::string &normalized_name)
	Validate and encode a user-supplied UTF-8 device name into the fixed Latin-1 write payload.
const char *	device_name_validation_error_name (DeviceNameValidationError error)
	Return a stable symbolic name for a device-name validation result.
const char *	device_name_validation_error_description (DeviceNameValidationError error)
	Return a human-readable explanation for a device-name validation result.
AddressClass	classify_address (const uint8_t addr[NODE_ID_SIZE])
	Classify an IO-Homecontrol 3-byte address.
const char *	address_class_name (AddressClass address_class)
	Get a human-readable name for an address classification.
DeviceType	broadcast_target_type (const uint8_t addr[NODE_ID_SIZE])
	Extract the target device type from a typed broadcast address.
void	encode_broadcast_address (DeviceType type, uint8_t out[NODE_ID_SIZE])
	Encode a device type into its typed-broadcast destination address — the exact inverse of broadcast_target_type(), kept immediately beside it so the pair cannot drift apart.
void	decode_1w_main_intent (uint8_t main0, uint8_t main1, char *out, size_t out_size)
	Decode the "main" position/command bytes from a 1W execute payload.
std::optional< float >	oneway_intent_to_target (uint8_t main0, uint8_t main1)
	Resolve a 1W main-byte pair to an optimistic IO target position, if unambiguous.
OneWayFrameInfo	decode_1w_frame (const IoFrame &frame)
	Decode a parsed 1W frame into a structured OneWayFrameInfo.
DiscoveryResponseInfo	decode_discovery_response (const IoFrame &frame, IoDevice &device, std::string &device_id)
	Decode a discovery-response payload (CMD_DISCOVER_RESP 0x29 or CMD_DISCOVER_SPE_RESP 0x2B — both carry the identical DISCOVERY_RESP_FULL_SIZE layout) into device metadata.
OneWayAddControllerDecodeError	decode_1w_add_controller (const IoFrame &frame, OneWayAdoptedKey &out)
	Decode a CMD_ONEWAY_ADD_CONTROLLER (0x30) frame into a recovered controller identity.
bool	create_execute_position (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t position, bool silent)
	Build a position execute command (0x00) to move a device to a numeric position.
bool	create_execute_command (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, CoverCommand cmd, bool silent)
	Build a named-command execute frame (0x00) for STOP, FAVORITE, or VENT.
bool	create_force_open (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t open_position)
	Build a force-open execute frame (0x00): an ordinary position command to the device's wire-scale "fully open" value, sent at elevated ACEI priority (see EXECUTE_ACEI_FORCE_OPEN).
bool	create_1w_execute_position (IoFrame &f, const uint8_t src[NODE_ID_SIZE], DeviceType target_type, uint8_t position, uint16_t sequence, const uint8_t controller_key[AES_KEY_SIZE], uint8_t acei, bool broadcast_all)
	Build a 1W position execute frame (CMD 0x00) targeting a device class.
bool	create_1w_execute_command (IoFrame &f, const uint8_t src[NODE_ID_SIZE], DeviceType target_type, CoverCommand cmd, uint16_t sequence, const uint8_t controller_key[AES_KEY_SIZE], uint8_t acei, bool broadcast_all)
	Build a 1W named-command execute frame (CMD 0x00) targeting a device class.
bool	create_1w_add_controller (IoFrame &f, const uint8_t src[NODE_ID_SIZE], DeviceType target_type, uint8_t manufacturer, uint16_t sequence, const uint8_t controller_key[AES_KEY_SIZE], bool with_mac)
	Build a 1W add-controller frame (CMD 0x30).
bool	create_1w_remove_controller (IoFrame &f, const uint8_t src[NODE_ID_SIZE], DeviceType target_type, uint16_t sequence, const uint8_t controller_key[AES_KEY_SIZE])
	Build a 1W remove-controller frame (CMD 0x39).
bool	create_private_function (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t function_id, uint8_t sub_index)
	Build a CMD_PRIVATE (0x03) request for an arbitrary function ID.
bool	create_get_status (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
	Build a get-status request (0x03). The device responds with its current position.
bool	create_get_name (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
	Build a get-name request (0x50).
bool	create_general_info3 (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
	Build a CMD_GET_GENERAL_INFO3 (0x58) request.
bool	create_get_info1 (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
	Build a CMD_GET_INFO1 (0x54) request. No payload. See proto_commands.h for the evidence note.
bool	create_get_info2 (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
	Build a CMD_GET_INFO2 (0x56) request. No payload. See proto_commands.h for the evidence note.
bool	create_set_name (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, const uint8_t payload[DEVICE_NAME_WRITE_PAYLOAD_SIZE])
	Build an authenticated set-name request (0x52) using a fixed zero-padded Latin-1 payload.
bool	create_identify (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
	Build an authenticated device-identify request (0x1E).
bool	create_write_private (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, const uint8_t *payload, size_t payload_len)
	Build a generic CMD_WRITE_PRIVATE (0x20) frame around a caller-supplied payload — the one builder behind every heating/climate function.
bool	create_execute_tilt (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t tilt_percent)
	Build a tilt execute command (0x00) for devices that support slat angle control.
bool	create_execute_position_and_tilt (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t position, uint8_t tilt_percent)
	Build a combined position-and-tilt execute command (0x00) — setClosureAndOrientation.
bool	create_get_status_extended (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t selector, uint8_t block, uint8_t function_id)
	Build an extended CMD_PRIVATE (0x03) request with a selector/block pair — the shape real hubs use for both the tilt block (selector STATUS_TILT_SELECTOR) and the field-observed selector 0x80 (tests/corpus/captures/probe/multi_somfy_probe_extended_private_both_selectors.yaml), which this codebase has never decoded.
bool	create_get_status_tilt (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
	Build a tilt-aware get-status request (0x03) that returns the extended 16-byte tilt payload.
bool	create_private2_read (IoFrame &f, const uint8_t *own, const uint8_t *dst, uint8_t modifier, bool long_form, bool low_power)
	Build a CMD_PRIVATE2 (0x0C) request in either of the two field-observed shapes.
bool	create_discover (IoFrame &f, const uint8_t *own)
	Build a discovery broadcast (0x28).
bool	create_discovery_request (IoFrame &f, const uint8_t *own, uint8_t command, const uint8_t *dst, bool low_power, bool payload_enabled, uint8_t payload, const uint8_t *system_key)
	Build a configurable discovery request command (0x28, 0x2A, or 0x2E).
bool	create_discover_resp (IoFrame &f, const uint8_t *own, const uint8_t *dst, DeviceType type, uint8_t subtype, uint8_t manufacturer_id)
	Build a discovery response (0x29) — device side, used only by the key-extraction responder.
static bool	create_device_terminal_ack (IoFrame &f, const uint8_t *own, const uint8_t *dst, uint8_t cmd)
	Build a bare device→hub terminal acknowledgement: no payload, END set, START and LOW_POWER clear.
bool	create_key_confirm (IoFrame &f, const uint8_t *own, const uint8_t *dst)
	Build a key-confirm frame (0x33) — device side, used only by the key-extraction responder.
bool	create_discover_confirm_ack (IoFrame &f, const uint8_t *own, const uint8_t *dst)
	Build a discovery-confirm acknowledgement (0x2D) — device side, used only by the key-extraction responder.
bool	recover_system_key_from_transfer (const uint8_t transfer_payload[AES_KEY_SIZE], const uint8_t challenge[HMAC_SIZE], uint8_t out_key[AES_KEY_SIZE])
	Recover the system key from a CMD_KEY_TRANSFER payload.
bool	create_key_init (IoFrame &f, const uint8_t *own, const uint8_t *dst)
	Build a key-init request (0x31) to start the pairing key exchange with a discovered device.
bool	create_key_transfer (IoFrame &f, IoFrame &old_frame, const uint8_t *dst, const uint8_t *src, const uint8_t key[AES_KEY_SIZE], const uint8_t challenge[HMAC_SIZE])
	Build a key-transfer frame (0x32) containing the system key encrypted with the transfer key.
static bool	create_challenge_req_framed (IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE], bool start, bool low_power)
	Build a challenge request (0x3C) with caller-chosen framing bits.
bool	create_challenge_req (IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE])
	Build a challenge request (0x3C) using a caller-supplied challenge.
bool	create_challenge_req (IoFrame &f, const uint8_t *dst, const uint8_t *src)
	Build a challenge request (0x3C) containing 6 random bytes.
bool	create_challenge_req_device_role (IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE])
	Build a device-role challenge request (0x3C) — device side, used only by the key-extraction responder.
static bool	create_challenge_resp_framed (IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE], const IoFrame &origin, const uint8_t *key, bool end, bool low_power)
	Build a challenge response (0x3D) with caller-chosen framing bits.
bool	create_challenge_resp (IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE], const IoFrame &origin, const uint8_t *key)
	Build a challenge response (0x3D) proving we know the system key.
bool	create_address_resp_device_role (IoFrame &f, const uint8_t *own, const uint8_t *dst)
	Build an address response (0x37) — device side, used only by the key-extraction responder.
bool	create_challenge_resp_device_role (IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE], const IoFrame &origin, const uint8_t *key)
	Build a device-role challenge response (0x3D) — device side, used only by the key-extraction responder answering a hub-issued 0x3C challenging our own 0x37.
bool	create_status_update_resp (IoFrame &f, const uint8_t *own, const uint8_t *dst)
	Build a status-update acknowledgment (0x72).
bool	create_set_config1 (IoFrame &f, const uint8_t *own, const uint8_t *dst)
	Build a set-config command (0x6F) to tell the device to automatically send status updates when controlled by any remote (not just us).
const char *	command_name (uint8_t cmd)
	Get a human-readable name for any IO-Homecontrol command ID.
const char *	manufacturer_name (uint8_t id)
	Get a human-readable manufacturer name from the protocol manufacturer byte.
const char *	att_class_name (uint8_t att_class)
	Get a human-readable turnaround time string for an ATT class value.
const char *	power_save_mode_name (uint8_t mode)
	Get a human-readable power save mode name.
const char *	originator_name (uint8_t originator)
	Get a human-readable name for a command originator byte.
const char *	acei_level_name (uint8_t level)
	Get a human-readable name for an ACEI priority level (0–7).
const char *	command_result_name (uint8_t result)
	Return a stable symbolic name for a CMD_ERROR_RESP result code.
const char *	command_result_description (uint8_t result)
	Return a human-readable explanation for a CMD_ERROR_RESP result code.
bool	is_limitation_result (uint8_t result)
	Check whether a result code represents an environmental or control limitation.
uint8_t	discovery_att_class (uint8_t flags)
	Extract the ATT class field from a discovery response's Multi Information Byte.
uint8_t	discovery_power_save_mode (uint8_t flags)
	Extract the power save mode field from a discovery response's Multi Information Byte.
bool	default_inverted_for_type (DeviceType type)
	Determine whether a device type has inverted position mapping by default.
const char *	cover_command_name (CoverCommand cmd)
	Get a human-readable name for a CoverCommand.
DeviceType	decode_packed_device_type (uint8_t type_msb, uint8_t type_subtype)
	Decode a protocol-packed device type from two metadata bytes.
uint8_t	decode_packed_device_subtype (uint8_t type_subtype)
	Decode a protocol-packed device subtype from the second metadata byte.
void	encode_packed_device_type (DeviceType type, uint8_t subtype, uint8_t &type_msb, uint8_t &type_subtype)
	Encode a DeviceType/subtype pair into the two-byte packed metadata format used by discovery responses — the inverse of decode_packed_device_type()/decode_packed_device_subtype().
void	decode_position_report (uint16_t target_raw, uint16_t current_raw, bool is_stopped, float &target, float &position)
	Decode target/current position values from a status frame.
bool	has_reached_target_position (float target, float position)
	Has the device reached its target within tolerance?
float	decode_tilt_report (uint16_t tilt_raw)
	Decode tilt angle from raw 16‑bit value.
const char *	device_type_name (DeviceType type)
	Convert a DeviceType to a lowercase string identifier.
const char *	yaml_device_type_name (DeviceType type)
	Return the YAML-friendly device-type name for types exposed in the Python schema.
DeviceCapabilityClass	device_capability_class (DeviceType type)
	Map a raw IO‑Homecontrol type to the closest ESPHome/Home Assistant entity family.
const char *	device_capability_class_name (DeviceType type)
	Get a human‑readable name for a capability class.
bool	device_supports_position_control (DeviceType type)
	Does this device type support precise position control (0–100)?
bool	device_supports_binary_control (DeviceType type)
	Does this device type support binary on/off control?
bool	device_supports_lock_control (DeviceType type)
	Does this device type support binary lock/unlock control via execute commands?
bool	device_supports_climate_control (DeviceType type)
	Does this device type support 2W climate/heating control (CMD_WRITE_PRIVATE 0x20)?
bool	device_supports_status_requests (DeviceType type)
	Does this device type support status request commands (0x03)?
bool	device_supports_tilt (DeviceType type)
	Does this device type support tilt (slat angle) control?
bool	device_supports_vent (DeviceType type)
	Does this device type support the ventilation position command?
const char *	device_operation_profile_name (DeviceType type)
	Human‑readable operation profile name for a device type.
std::string	format_device_type_diagnostic (DeviceType type)
	Human-readable device type string for diagnostics, including the raw numeric value.
std::string	format_device_type_for_yaml (DeviceType type)
	Build the YAML value for a device's io_device_type key.
std::string	build_device_yaml_snippet (DeviceType type, uint8_t subtype, const std::string &device_id, bool metadata_complete, bool inverted, bool low_power)
	Build the ready-to-paste YAML block describing a device, for both a fully-decoded device and one whose type/subtype wasn't reported.
int16_t	rssi_scaled_to_dbm (int16_t scaled)
	Convert an rssi_ema_scaled fixed-point value to whole dBm (round half away from zero).
int16_t	device_rssi_ema_dbm (const IoDevice &dev)
	A device's smoothed RSSI in whole dBm.
float	effective_target (const IoDevice &dev)
	The main-position target a consumer should act on: the prediction when one stands, otherwise the device's own last reported target.
float	effective_tilt (const IoDevice &dev)
	The slat angle a consumer should act on, prediction first.
bool	effective_is_stopped (const IoDevice &dev)
	Whether a consumer should treat the device as at rest, prediction first.
static int	hex_nibble (char ch)
bool	hex_to_bytes (const std::string &hex, uint8_t *out, uint8_t len)
	Convert a hex string (e.g., "123ABC") to a byte array.
std::string	node_id_to_string (const uint8_t id[NODE_ID_SIZE])
	Format a 3‑byte node ID as a 6‑character uppercase hex string.
uint16_t	crc_ccitt (const uint8_t *data, uint8_t len)
	CRC-CCITT used by the IO-Homecontrol protocol for frame validation.
void	init_frame (IoFrame &f, bool is_2w=true, bool start=false, bool end=false, bool low_power=false)
	Initialize an IoFrame header (ctrl0/ctrl1) with flags.
void	set_dst (IoFrame &f, const uint8_t id[NODE_ID_SIZE])
	Set destination node ID.
void	set_src (IoFrame &f, const uint8_t id[NODE_ID_SIZE])
	Set source node ID.
bool	set_cmd (IoFrame &f, uint8_t cmd, const uint8_t *params=nullptr, uint8_t params_len=0)
	Set command and payload.
uint8_t	frame_length (const IoFrame &f)
	Get total frame length from ctrl0.
bool	is_start (const IoFrame &f)
	Check START flag.
bool	is_end (const IoFrame &f)
	Check END flag.
bool	frame_carries_mac_trailer (uint8_t cmd)
	Whether wire frames for a command carry the out-of-length MAC trailer described on IoFrame::has_mac/IoFrame::mac.
uint8_t	serialize (const IoFrame &f, uint8_t *buf, uint8_t buf_size)
	Serialize a parsed frame into a wire buffer (without CRC).
bool	parse (const uint8_t *buf, uint8_t buf_len, IoFrame &f)
	Parse a wire buffer into a parsed IoFrame (validates length and CTRL0).
const char *	heating_function_name (HeatingFunction fn)
	Stable lowercase name for a heating function ("power_on", "set_temperature", ...).
size_t	encode_heating_payload (HeatingFunction fn, float value, uint8_t out[HEATING_PAYLOAD_MAX_SIZE])
	Encode one heating function into a CMD_WRITE_PRIVATE (0x20) payload.
constexpr bool	lr1121_firmware_is_outdated (uint8_t fw_major, uint8_t fw_minor)
	Pure comparison against the known-latest constants above — no I/O, host-testable.
uint8_t	decode_uart_probe (const uint8_t *raw, uint8_t raw_len, uint8_t bit_offset, uint8_t *decoded, uint8_t decoded_max_len)
	Decode a raw UART‑encoded bitstream into bytes.
bool	is_known_io_command (uint8_t cmd)
	This list missing CMD_GET_GENERAL_INFO3_RESP (0x59) is exactly what turned a real Q2 probe reply into a false "no reply" timeout on real hardware (2026-08-16); the same audit also found CMD_IDENTIFY and CMD_WRITE_PRIVATE/CMD_WRITE_PRIVATE_ACK missing, unrelated to that probe but affecting the already-shipped identify_device() action (and climate writes) on SX1262/LR1121.
static std::pair< uint8_t, uint8_t >	find_crc_valid_frame (const uint8_t *decoded, uint8_t decoded_len)
	Try to find a CRC-valid IO-Homecontrol frame within a decoded UART byte stream.
UartProbeResult	find_uart_probe (const uint8_t *raw, uint8_t raw_len)
	Search raw RX buffer for the best CRC-validated IO-Homecontrol frame.
uint8_t	soft_phy_raw_bytes_for_frame (uint8_t frame_len)
	Raw on-air bytes needed to carry a whole frame: frame_len protocol bytes plus the two trailing CRC bytes, each UART-packed into a 10-bit cell.
uint8_t	soft_phy_peek_frame_length (const uint8_t *raw, uint8_t raw_len)
	Recover a frame's total length from the very first UART cell of a reception.
uint8_t	uart_encode_packet (const uint8_t *data, uint8_t len, uint8_t *encoded, uint8_t encoded_max_len)
	UART-encode a buffer of bytes (start bit 0, 8 data bits LSB-first, stop bit 1).
constexpr uint32_t	soft_phy_air_time_us (uint32_t raw_bytes)
	On-air time in microseconds for raw_bytes bytes at the protocol's line rate.
bool	command_carries_key_material (uint8_t cmd)
	Whether a frame command's payload carries key material that must never be logged or reported verbatim.
bool	contains_key_material (const uint8_t *buf, size_t len, const uint8_t *system_key)
	Whether a buffer contains the system key as a contiguous run of bytes.
uint32_t	settle_delay_ms (uint32_t interval_ms, uint32_t hint_delay_ms, bool cap_for_stop)
	Resolve the follow-up settle-poll delay while a device may still be moving.
float	bandwidth_to_khz (const BandwidthOption *table, size_t n, uint8_t reg, float fallback)
	Look up the kHz value for a register byte in a bandwidth table.
std::string	bandwidth_to_string (float khz)
	Format a kHz value as its YAML/UI option string (bare number, one decimal, e.g. "117.3").
std::optional< uint8_t >	bandwidth_from_string (const BandwidthOption *table, size_t n, const std::string &value)
	Parse a YAML/UI bandwidth string against a table, returning the matching register byte.
BandwidthTableView	sx1262_bandwidth_table ()
	The SX1262 RX-bandwidth option table.
BandwidthTableView	sx1276_bandwidth_table ()
	The SX1276 RX-bandwidth option table (see sx1262_bandwidth_table()).
BandwidthTableView	lr1121_bandwidth_table ()
	The LR1121 RX-bandwidth option table (see sx1262_bandwidth_table()).
float	sx1262_bandwidth_to_khz (SX1262RxBandwidth bw)
	Convert a bandwidth enum to the numeric kHz value used in YAML/logs.
std::string	sx1262_bandwidth_to_string (SX1262RxBandwidth bw)
	Format a bandwidth enum as its YAML/UI option string (bare kHz number, e.g.
std::optional< SX1262RxBandwidth >	sx1262_bandwidth_from_string (const std::string &value)
	Convert a YAML bandwidth string to the enum value.
float	sx1276_bandwidth_to_khz (SX1276RxBandwidth bw)
	Convert an SX1276 bandwidth enum to the numeric kHz value used in YAML/logs.
std::string	sx1276_bandwidth_to_string (SX1276RxBandwidth bw)
	Format an SX1276 bandwidth enum as its YAML/UI option string (bare kHz number).
std::optional< SX1276RxBandwidth >	sx1276_bandwidth_from_string (const std::string &value)
	Convert a YAML SX1276 bandwidth string to the enum value.
float	lr1121_bandwidth_to_khz (LR1121RxBandwidth bw)
	Convert an LR1121 bandwidth enum to the numeric kHz value used in YAML/logs.
std::string	lr1121_bandwidth_to_string (LR1121RxBandwidth bw)
	Format an LR1121 bandwidth enum as its YAML/UI option string (bare kHz number).
std::optional< LR1121RxBandwidth >	lr1121_bandwidth_from_string (const std::string &value)
	Convert a YAML LR1121 bandwidth string to the enum value.
std::optional< DiscoveryCommand >	discovery_command_from_string (const std::string &value)
	Parse a discovery command string (e.g., "0x28") into the enum.
std::string	discovery_command_to_string (DiscoveryCommand cmd)
	Format a discovery command enum for YAML/logs.
std::string	discovery_commands_to_csv (const std::vector< DiscoveryCommand > &commands)
	Format the ordered discovery command list as a UI/preset option string.
std::string	discovery_commands_to_string (const std::vector< DiscoveryCommand > &commands)
	Format the ordered discovery command list for logs.
const uint8_t *	resolve_discovery_destination (uint8_t command, bool destination_auto, const uint8_t destination[NODE_ID_SIZE])
	Resolve the destination address for a discovery command.
std::string	discovery_destination_to_string (bool destination_auto, const uint8_t destination[NODE_ID_SIZE])
	Format a destination option for YAML/logs.
std::string	discovery_payload_to_string (bool payload_enabled, uint8_t payload)
	Format a payload option for YAML/logs.
std::string	tuning_update_log_line (const std::string &name, const std::string &value)
	Format a single tuning update for the log.
std::string	tuning_config_snapshot (const TuningConfig &cfg)
	Format the current tuning configuration as a one-line YAML-compatible snapshot.
std::string	tuning_config_full_snapshot (const TuningConfig &cfg)
	Format the current tuning configuration as a full one-line snapshot.
const TuningNumberParam *	find_tuning_number (const std::string &name)
	Look up a numeric tuning parameter by name; returns nullptr if unknown.
const TuningSelectParam *	find_tuning_select (const std::string &name)
	Look up a select tuning parameter by name; returns nullptr if unknown.
Table iteration
Range accessors over the full parameter tables, for enumeration and tests.
const TuningNumberParam *	tuning_number_params_begin ()
const TuningNumberParam *	tuning_number_params_end ()
const TuningSelectParam *	tuning_select_params_begin ()
const TuningSelectParam *	tuning_select_params_end ()

Variables
static constexpr const char *	TAG = "home_io_control"
static const char *const	TAG = "home_io_control.exchange"
static const char *const	TAG = detail::TAG
constexpr uint8_t	DEFAULT_TX_POWER_DBM = 17
	Default TX power used unless YAML overrides it.
constexpr uint8_t	DEFAULT_PA_PIN_PA_BOOST = 0x80
	SX1276 PA_CONFIG selector for the PA_BOOST output path.
constexpr uint8_t	DEFAULT_TCXO_VOLTAGE_SETTING_1P8V = 0x03
	SX1262 DIO3 setting value for a 1.8 V TCXO.
constexpr size_t	POSITION_TEXT_BUFFER_SIZE = 16
	Buffer for formatted position strings such as "100%".
constexpr size_t	FRAME_LOG_HEX_BUFFER_SIZE = 220
	Fits a full 32-byte frame rendered as spaced hex text.
constexpr size_t	FRAME_LOG_FLAGS_BUFFER_SIZE = 32
	Buffer for decoded CTRL1 flag annotations.
constexpr uint8_t	LR1121_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS = 0x03
	LR1121 GetVersion type byte in normal mode — must match radio_lr1121.h's LR1121_DEVICE_TYPE (0x03).
constexpr uint8_t	LR1110_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS = 0x01
	Normal-mode GetVersion type bytes for the two chips an LR1121 is most easily confused with — companions to LR1121_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS above, used only to name the chip family in a REJECT_WRONG_CHIP message.
constexpr uint8_t	LR1120_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS = 0x02
constexpr uint8_t	LR1121_BOOTLOADER_TYPE_FOR_FIRMWARE_DECISIONS = 0xDF
	LR1121 GetVersion type byte reported while running the bootloader (LR11XX_TYPE_PRODUCTION_MODE) — must match radio_lr1121_firmware_updater.h's LR1121_UPDATER_BOOTLOADER_TYPE (0xDF).
constexpr uint16_t	LR1121_BOOTLOADER_2100 = 0x2100
	LR1121 bootloader versions, from Semtech's published compatibility matrix.
constexpr uint16_t	LR1121_BOOTLOADER_2101 = 0x2101
constexpr uint16_t	LR1120_BOOTLOADER_2000 = 0x2000
	Bootloader versions reported by the two chips an LR1121 is most easily confused with — used only to name the chip family in a REJECT_WRONG_CHIP message.
constexpr uint16_t	LR1120_BOOTLOADER_2001 = 0x2001
constexpr uint16_t	LR1110_BOOTLOADER_6500 = 0x6500
constexpr uint16_t	LR1110_BOOTLOADER_1001 = 0x1001
constexpr uint16_t	LR1121_LOADER_2100 = 0x2100
	Version the lr1121_loader_2100.bin bootloader-*loader* image reports of itself.
constexpr Lr1121BootloaderRequirement	LR1121_KNOWN_BOOTLOADER_REQUIREMENTS []
	Bootloader requirements we know about, copied from Semtech's published pairings (SWTL001/application/src/lr11xx_update_utils.c :: compatibility_matrix[]): 0x0101/0x0102/0x0103 need bootloader 0x2100, 0x0104 needs 0x2101.
static constexpr std::array< DeviceType, 3 >	VELUX_KLI_ENROLLMENT_CLASSES
	The three device classes a real VELUX KLI PROG gesture sweeps its 0x30 across — roller shutter, awning, dual shutter — and never any other (issue #74 capture, decoded with broadcast_target_type(); matches samr037/iohc-flipper's PAIR_DST_{WINDOW,SHUTTER,OTHER}).
static constexpr uint8_t	ONEWAY_POSITION_FULLY_OPEN = 0
	Wire-scale position meaning "fully closed" (0 means fully open).
static constexpr uint8_t	ONEWAY_POSITION_FULLY_CLOSED = 100
static constexpr uint16_t	ONEWAY_SEQUENCE_ACCEPTANCE_WINDOW = 1000
	How far ahead of its stored high-water mark a device will still accept a jump.
static constexpr uint16_t	ONEWAY_SEQUENCE_STRIDE = 8
	How many sequences one flash write reserves.
static constexpr uint16_t	ONEWAY_SEQUENCE_REBOOT_HEADROOM = 8
	How many consecutive unclean reboots the stride must survive while staying inside a device's acceptance window.
static constexpr uint8_t	BINARY_ENTITY_ON_POSITION = 0
	Position value written for binary ON commands (light on, switch on, lock unlock).
static constexpr uint8_t	BINARY_ENTITY_OFF_POSITION = 100
	Position value written for binary OFF commands (light off, switch off, lock lock).
static constexpr uint8_t	PAIRING_TELEMETRY_MAX_EVENTS = 32
	Maximum number of events recorded per pairing attempt.
static const char *const	TAG = "home_io_control.climate"
static const char *const	TAG = "home_io_control.cover"
static const char *const	TAG_COMMAND_BUTTON = "home_io_control.cover_command_button"
static const char *const	TAG_SILENT = "home_io_control.cover.silent"
static const char *const	TAG = "home_io_control.light"
static const char *const	TAG = "home_io_control.lock"
static const char *const	TAG = "home_io_control.switch"
static constexpr uint8_t	ONEWAY_EXECUTE_MIN_DATA_LEN = 4
	Minimum data bytes for decode of execute/activate‑mode intent fields.
static constexpr uint8_t	DEVICE_NAME_WRITE_CHAR_LIMIT = 15
	Reference write limit before the trailing null.
static constexpr uint8_t	DEVICE_NAME_WRITE_PAYLOAD_SIZE
	Fixed write payload: 15 visible chars plus trailing null/padding.
static constexpr uint16_t	LATIN1_CODEPOINT_MAX = 0x00FF
	Highest Unicode code point representable in Latin-1.
static constexpr size_t	ONEWAY_INTENT_BUFFER_SIZE = 24
	Buffer size for the decoded 1W main-intent string.
static constexpr uint8_t	CMD_EXECUTE = 0x00
	Set position/open/close/stop — requires authentication.
static constexpr uint8_t	CMD_ACTIVATE_MODE = 0x01
	Activate device mode (scene, ventilation) — requires auth.
static constexpr uint8_t	CMD_PRIVATE = 0x03
	Get device status — no authentication needed.
static constexpr uint8_t	CMD_PRIVATE_RESP = 0x04
	Response to 0x00 and 0x03 (contains position data).
static constexpr uint8_t	CMD_PRIVATE2
	Content otherwise undecoded by the wire parser.
static constexpr uint8_t	CMD_PRIVATE2_RESP = 0x0D
	Response to CMD_PRIVATE2. See CMD_PRIVATE2's comment.
static constexpr uint8_t	CMD_SET_SENSOR
	Inject sensor value into a device.
static constexpr uint8_t	CMD_SET_SENSOR_ACK = 0x1A
	Acknowledgment to CMD_SET_SENSOR.
static constexpr uint8_t	CMD_IDENTIFY = 0x1E
	Device physical identification / jog — requires authentication.
static constexpr uint8_t	CMD_WRITE_PRIVATE = 0x20
	Write private register (climate/heating devices).
static constexpr uint8_t	CMD_WRITE_PRIVATE_ACK = 0x21
	Acknowledgment to CMD_WRITE_PRIVATE.
static constexpr uint8_t	CMD_DISCOVER_REQ = 0x28
	Broadcast discovery request.
static constexpr uint8_t	CMD_DISCOVER_RESP = 0x29
	Device responds with its ID and type.
static constexpr uint8_t	CMD_DISCOVER_SPE_REQ
	Broadcast roll-call answered by every device that already holds this controller's system key, regardless of device type.
static constexpr uint8_t	CMD_DISCOVER_SPE_RESP
	Roll-call reply to CMD_DISCOVER_SPE_REQ, sent only by devices that already hold the requesting controller's system key.
static constexpr uint8_t	CMD_DISCOVER_CONFIRM = 0x2C
	Confirm discovery to device.
static constexpr uint8_t	CMD_DISCOVER_CONFIRM_ACK = 0x2D
	Device acknowledges confirmation.
static constexpr uint8_t	CMD_DISCOVER_ALT_REQ
	Alternate discovery.
static constexpr uint8_t	CMD_DISCOVER_ALT_RESP
	Reply to an addressed (non-broadcast) CMD_DISCOVER_ALT_REQ, following a 0x3C/0x3D challenge-response.
static constexpr uint8_t	CMD_ONEWAY_ADD_CONTROLLER
	1W "add controller" — a 1W device broadcasts this while its key-copy gesture is active, handing its network's wrapped system key to whichever controller is listening.
static constexpr uint8_t	CMD_ONEWAY_REMOVE = 0x39
	1W "remove controller" (un-pair a 1W remote from a device); same payload shape as 0x2E.
static constexpr uint8_t	CMD_KEY_INIT = 0x31
	Initiate key transfer to device.
static constexpr uint8_t	CMD_KEY_TRANSFER = 0x32
	Send encrypted system key to device.
static constexpr uint8_t	CMD_KEY_CONFIRM = 0x33
	Device confirms key was received.
static constexpr uint8_t	CMD_ADDRESS_REQ
	"Report your address" request.
static constexpr uint8_t	CMD_ADDRESS_RESP
	Address assignment response: the device returns its own 3-byte backbone address, byte-identical to the one it reported at data[2..4] (DISCOVERY_RESP_BACKBONE_OFFSET) of its CMD_DISCOVER_RESP earlier in the same session — an independent confirmation of that offset.
static constexpr uint8_t	CMD_LAUNCH_KEY_TRANSFER
	Device-initiated ("pull") key transfer request: documented elsewhere as a command ID plus a 6-byte challenge, nothing more — never observed in our corpus or in any field log, and not sent or handled anywhere in this codebase — the constant is used only to construct a hypothetical device-side IV in tests/proto_crypto_test.cpp, exercising the crypto primitive, not a dispatch path.
static constexpr uint8_t	CMD_CHALLENGE_REQ
	6-byte random challenge.
static constexpr uint8_t	CMD_CHALLENGE_RESP
	HMAC proof answering a 0x3C.
static constexpr uint8_t	CMD_UNKNOWN4A_REQ
	Content undecoded.
static constexpr uint8_t	CMD_UNKNOWN4A_RESP
	Observed on the wire (tests/corpus/captures/probe/velux_kig300_probe_capability_burst.yaml) answering an ON_OFF_SWITCH-type device's traffic, but its request opcode is unconfirmed — it is not established to be CMD_UNKNOWN4A_REQ's reply rather than CMD_GET_GENERAL_INFO3's.
static constexpr uint8_t	CMD_GET_NAME = 0x50
	Request device name.
static constexpr uint8_t	CMD_GET_NAME_RESP = 0x51
	Device name response.
static constexpr uint8_t	CMD_SET_NAME = 0x52
	Set device name (authenticated).
static constexpr uint8_t	CMD_SET_NAME_RESP = 0x53
	Device-name write response.
static constexpr uint8_t	CMD_GET_INFO1
	Request device general info 1.
static constexpr uint8_t	CMD_GET_INFO1_RESP = 0x55
	Device general info 1 response.
static constexpr uint8_t	CMD_GET_INFO2 = 0x56
	Request device type/model info.
static constexpr uint8_t	CMD_GET_INFO2_RESP = 0x57
	Device type/model response.
static constexpr uint8_t	CMD_GET_GENERAL_INFO3
	Observed on the wire (tests/corpus/captures/probe/velux_kig300_probe_capability_burst.yaml) with no payload.
static constexpr uint8_t	CMD_GET_GENERAL_INFO3_RESP
	Never captured on our own wire.
static constexpr uint8_t	CMD_SET_CONFIG1 = 0x6F
	Configure device to auto-send status updates.
static constexpr uint8_t	CMD_SET_CONFIG1_RESP
	Config response, otherwise undocumented.
static constexpr uint8_t	CMD_STATUS_UPDATE = 0x71
	Device-initiated status update (needs auth).
static constexpr uint8_t	CMD_STATUS_UPDATE_RESP = 0x72
	Acknowledge status update.
static constexpr uint8_t	CMD_SEND_RAW_MESSAGE
	Named "Send Raw Message" / "Find Hardware" — two candidate names, neither settled.
static constexpr uint8_t	CMD_READ_GROUPS
	Named "Actuator: Read Groups" / "ActuatorAnyConfigIsLocal" (uncertain) / "Service ACK" — three candidate names, one itself flagged uncertain.
static constexpr uint8_t	CMD_REBOOT
	Named "Reboot" / "Service Status" — two candidate names, one of them destructive-sounding, on no field evidence at all.
static constexpr uint8_t	CMD_SERVICE_STATUS_ACK = 0xF3
	No description available at all for this opcode, not even a hedge.
static constexpr uint8_t	CMD_ERROR_RESP = 0xFE
	Error response to any command.
static constexpr uint8_t	RESULT_UNKNOWN_STATUS_REPLY = 0x00
	Device returned an unknown status reply.
static constexpr uint8_t	RESULT_COMMAND_COMPLETED_OK = 0x01
	No errors detected.
static constexpr uint8_t	RESULT_NO_CONTACT = 0x02
	No communication to node.
static constexpr uint8_t	RESULT_MANUALLY_OPERATED = 0x03
	Manually operated by a user.
static constexpr uint8_t	RESULT_BLOCKED = 0x04
	Node blocked by an object.
static constexpr uint8_t	RESULT_WRONG_SYSTEMKEY = 0x05
	Node contains the wrong system key.
static constexpr uint8_t	RESULT_PRIORITY_LEVEL_LOCKED = 0x06
	Node is locked on this priority level.
static constexpr uint8_t	RESULT_REACHED_WRONG_POSITION = 0x07
	Node stopped in another position than expected.
static constexpr uint8_t	RESULT_ERROR_DURING_EXECUTION = 0x08
	Generic execution failure.
static constexpr uint8_t	RESULT_NO_EXECUTION = 0x09
	Node did not move.
static constexpr uint8_t	RESULT_CALIBRATING = 0x0A
	Node is calibrating.
static constexpr uint8_t	RESULT_POWER_CONSUMPTION_TOO_HIGH = 0x0B
	Node power consumption is too high.
static constexpr uint8_t	RESULT_POWER_CONSUMPTION_TOO_LOW = 0x0C
	Node power consumption is too low.
static constexpr uint8_t	RESULT_LOCK_POSITION_OPEN = 0x0D
	Lock command failed because the door is open.
static constexpr uint8_t	RESULT_MOTION_TIME_TOO_LONG = 0x0E
	Target was not reached in time.
static constexpr uint8_t	RESULT_THERMAL_PROTECTION = 0x0F
	Node entered thermal protection mode.
static constexpr uint8_t	RESULT_PRODUCT_NOT_OPERATIONAL = 0x10
	Node is not currently operational.
static constexpr uint8_t	RESULT_FILTER_MAINTENANCE_NEEDED = 0x11
	Filter needs maintenance.
static constexpr uint8_t	RESULT_BATTERY_LEVEL = 0x12
	Battery level is low.
static constexpr uint8_t	RESULT_TARGET_MODIFIED = 0x13
	Node modified the requested target value.
static constexpr uint8_t	RESULT_MODE_NOT_IMPLEMENTED = 0x14
	Mode is not supported by the node.
static constexpr uint8_t	RESULT_COMMAND_INCOMPATIBLE_TO_MOVEMENT = 0x15
	Command cannot move the node that way.
static constexpr uint8_t	RESULT_USER_ACTION = 0x16
	User action overrode the command.
static constexpr uint8_t	RESULT_DEAD_BOLT_ERROR = 0x17
	Dead bolt error.
static constexpr uint8_t	RESULT_AUTOMATIC_CYCLE_ENGAGED = 0x18
	Node entered automatic cycle mode.
static constexpr uint8_t	RESULT_WRONG_LOAD_CONNECTED = 0x19
	Wrong load connected to node.
static constexpr uint8_t	RESULT_COLOUR_NOT_REACHABLE = 0x1A
	Requested colour not reachable.
static constexpr uint8_t	RESULT_TARGET_NOT_REACHABLE = 0x1B
	Requested target not reachable.
static constexpr uint8_t	RESULT_BAD_INDEX_RECEIVED = 0x1C
	Invalid index received.
static constexpr uint8_t	RESULT_COMMAND_OVERRULED = 0x1D
	Command was overruled by a newer command.
static constexpr uint8_t	RESULT_NODE_WAITING_FOR_POWER = 0x1E
	Node is waiting for power.
static constexpr uint8_t	RESULT_NODE_LOCKED = 0x20
	Node is locked.
static constexpr uint8_t	RESULT_WRONG_POSITION = 0x21
	Node reports wrong position.
static constexpr uint8_t	RESULT_LIMITS_NOT_SET = 0x22
	Device limits are not set.
static constexpr uint8_t	RESULT_IP_NOT_SET = 0x23
	Intermediate position is not set.
static constexpr uint8_t	RESULT_OUT_OF_RANGE = 0x24
	Requested value is out of range.
static constexpr uint8_t	RESULT_PRIORITY_LOCKED_NON_EXEC
	Priority locked, command not executed (ACEI priority too low).
static constexpr uint8_t	RESULT_INVALID_FUNCTION_INDEX
	CMD_PRIVATE-family function ID / sub-index / selector-block outside the range the device implements.
static constexpr uint8_t	RESULT_INFORMATION_CODE = 0xDF
	Information-only code with unknown semantics.
static constexpr uint8_t	RESULT_PARAMETER_LIMITED = 0xE0
	Parameter limited by an unknown device.
static constexpr uint8_t	RESULT_LIMITATION_BY_LOCAL_USER = 0xE1
	Parameter limited by local button.
static constexpr uint8_t	RESULT_LIMITATION_BY_USER = 0xE2
	Parameter limited by a remote control.
static constexpr uint8_t	RESULT_LIMITATION_BY_RAIN = 0xE3
	Parameter limited by a rain sensor.
static constexpr uint8_t	RESULT_LIMITATION_BY_TIMER = 0xE4
	Parameter limited by a timer.
static constexpr uint8_t	RESULT_LIMITATION_BY_SCD = 0xE5
	Parameter limited by a security actuator.
static constexpr uint8_t	RESULT_LIMITATION_BY_UPS = 0xE6
	Parameter limited by a power supply.
static constexpr uint8_t	RESULT_LIMITATION_BY_UNKNOWN_DEVICE = 0xE7
	Parameter limited by an unknown device.
static constexpr uint8_t	RESULT_LIMITATION_BY_SAAC = 0xEA
	Parameter limited by a standalone automatic controller.
static constexpr uint8_t	RESULT_LIMITATION_BY_WIND = 0xEB
	Parameter limited by a wind sensor.
static constexpr uint8_t	RESULT_LIMITATION_BY_MYSELF = 0xEC
	Parameter limited by the node itself.
static constexpr uint8_t	RESULT_LIMITATION_BY_AUTOMATIC_CYCLE = 0xED
	Parameter limited by an automatic cycle.
static constexpr uint8_t	RESULT_LIMITATION_BY_EMERGENCY = 0xEE
	Parameter limited by an emergency.
static constexpr uint8_t	POS_STOP = 0xD2
	Position values in the IO protocol.
static constexpr uint8_t	POS_UNKNOWN = 0xD4
	Wire value: position unknown / keep current.
static constexpr uint8_t	POS_FAVORITE = 0xD8
	Wire value: move to favorite/"My" position.
static constexpr uint8_t	POS_SECURED_TARGET = 0xD1
	Wire value for the secured target position command.
static constexpr uint8_t	POS_DEFAULT = 0xD3
	Wire value for the default position command.
static constexpr uint8_t	POS_FORCE_OPEN = 0x64
	Ambiguous wire value used only for passive 1W-traffic intent decoding (decode_1w_main_intent() / oneway_intent_to_target() in proto_codecs.cpp).
static constexpr uint8_t	POS_VENT_MODIFIER = 0x03
	Modifier byte for the ventilation command.
static constexpr uint8_t	POSITION_WIRE_SCALE = 2
	Scale factor between a 0-100 percent position and its CMD_EXECUTE main-byte wire value.
static constexpr uint8_t	POSITION_WIRE_MAX = 200
	Highest doubled-position wire value: 100% * POSITION_WIRE_SCALE.
static constexpr uint8_t	STATUS_STOPPED = 0x01
	Status byte flags in CMD_PRIVATE_RESP and CMD_STATUS_UPDATE.
static constexpr uint8_t	STATUS_EXPECTED = 0x80
	Byte 1 bit 7: device will send auto status update.
static constexpr uint8_t	STATUS_TILT_SELECTOR = 0x20
	Extended status payload marker for tilt-capable devices.
static constexpr uint8_t	PRIVATE_GET_POSITION_STATUS = 0x03
	CMD_PRIVATE (0x03) function ID for a position-status request — data[0] of the payload.
static constexpr uint8_t	TRANSFER_KEY [AES_KEY_SIZE]
	The transfer key is a hardcoded key used ONLY during pairing to obfuscate the system key during over-the-air transfer.
static constexpr uint16_t	CRC_POLYNOMIAL_REVERSED = 0x8408
	Reversed CRC-CCITT polynomial used by IO-homecontrol.
static constexpr uint16_t	CRC_LSB_MASK = 0x0001
	Least-significant-bit mask for reflected CRC update.
static constexpr uint8_t	BROADCAST_DISCOVER [NODE_ID_SIZE] = {0x00, 0x00, 0x3B}
	Broadcast address for device discovery (0x00003B).
static constexpr uint8_t	BROADCAST_DISCOVER_ALT [NODE_ID_SIZE] = {0x00, 0x00, 0x3F}
	Alternate discovery / 1W broadcast address (0x00003F).
static constexpr uint8_t	MANUFACTURER_ID_MAX = 12
	Maximum manufacturer ID with a known name in the lookup table.
static constexpr uint8_t	ONEWAY_EXECUTE_ACEI
	ACEI byte for a 1W CMD_EXECUTE frame — the Somfy-shaped default.
static constexpr uint8_t	ONEWAY_EXECUTE_ACEI_VELUX = (ACEI_LEVEL_USER_DEFAULT << ACEI_LEVEL_SHIFT) | ACEI_VALID_BIT
	ACEI byte for a 1W CMD_EXECUTE frame from a VELUX KLI-class remote.
static constexpr uint16_t	STATUS_POS_MAX = 0xC800
	In status responses, position is encoded as a 16-bit value where 0x0000 = fully open (0%) and 0xC800 = fully closed (100%).
static constexpr uint16_t	STATUS_POS_TOLERANCE_RAW = 100
	Target-reached tolerance expressed in raw IO-homecontrol position units.
static constexpr uint8_t	DEVICE_METADATA_SIZE = 2
	Packed device metadata uses two bytes where the high 8 bits carry the upper type bits and the low byte carries both the remaining type bits and the 6-bit manufacturer subtype.
static constexpr uint8_t	DEVICE_TYPE_LOW_BITS_SHIFT = 2
static constexpr uint8_t	DEVICE_TYPE_HIGH_BITS_SHIFT = 6
static constexpr uint8_t	DEVICE_SUBTYPE_MASK = 0x3F
static constexpr float	UNKNOWN_POSITION = 212.0F
	Sentinel value meaning "position is not known yet".
static constexpr uint8_t	DEVICE_NAME_BUFFER_SIZE = 32
	Device name storage including null terminator.
static constexpr int16_t	RSSI_UNKNOWN_DBM = INT16_MIN
	Sentinel value meaning "no RSSI sample recorded yet" for last_rssi_dbm/rssi_ema_scaled.
static constexpr int16_t	RSSI_EMA_SCALE = 8
	EMA weight denominator and fixed-point scale for IoDevice::rssi_ema_scaled.
static constexpr uint8_t	CTRL0_END = 0x80
	Control byte 0 (CTRL0) bit definitions.
static constexpr uint8_t	CTRL0_START = 0x40
	Bit 6: first frame in exchange.
static constexpr uint8_t	CTRL0_PROTOCOL_1W = 0x20
	Bit 5: 1=OneWay protocol, 0=TwoWay protocol.
static constexpr uint8_t	CTRL0_LENGTH_MASK = 0x1F
	Bits [4:0]: frame length - 1.
static constexpr uint8_t	CTRL1_VERSION_MASK = 0x03
	Ties FRAME_MAX_DECLARED_SIZE (proto_sizes.h) to the mask that actually defines it.
static constexpr uint8_t	CTRL1_PRIORITY = 0x04
	Bit 2: high-priority frame.
static constexpr uint8_t	CTRL1_ACK = 0x10
	Bit 4: sender can handle 2W responses (ACK-capable).
static constexpr uint8_t	CTRL1_LOW_POWER = 0x20
	Bit 5: low-power device (e.g., solar-powered).
static constexpr uint8_t	CTRL1_ROUTED = 0x40
	Bit 6: frame was relayed through a repeater.
static constexpr uint8_t	CTRL1_BEACON = 0x80
	Bit 7: beacon announcement frame.
constexpr float	HEATING_TEMP_MIN_C = 7.0F
	Lowest setpoint this codec will encode.
constexpr float	HEATING_TEMP_MAX_C = 28.0F
	Highest setpoint this codec will encode.
constexpr size_t	HEATING_PAYLOAD_MAX_SIZE = 6
	Largest payload any function produces — SET_TEMPERATURE's 6-byte form (iohcCozyDevice2W.cpp:125).
constexpr uint8_t	HEATING_PAYLOAD_PREFIX = 0x0C
	Leading payload byte, common to every function (iohcCozyDevice2W.cpp:105 et al.).
constexpr uint8_t	HEATING_REGISTER_HIGH_BYTE = 0x01
	Payload byte at index 2 — the high byte of the 16-bit register number, constant 0x01 (registers are 0x01xx) per AtlanticThermor/README.md ("Set 0c61 01xx" / "Get 0c60 01xx").
static constexpr uint8_t	NODE_ID_SIZE = 3
	Device/node addresses are 3 bytes (e.g., "123ABC").
static constexpr uint8_t	NODE_ID_STRING_SIZE = (NODE_ID_SIZE * 2) + 1
	Uppercase hex node ID plus null terminator.
static constexpr uint8_t	HMAC_SIZE = 6
	Authentication HMAC is 6 bytes (truncated AES output).
static constexpr uint8_t	AES_KEY_SIZE = 16
	AES-128 key size.
static constexpr uint8_t	AES_BLOCK_SIZE = 16
	AES block size.
static constexpr uint8_t	IV_SIZE = 16
	Initialization vector size for AES.
static constexpr uint8_t	IV_PADDING = 0x55
	Padding byte used in IV construction.
static constexpr uint8_t	BITS_PER_BYTE = 8
	Number of bits in one protocol byte.
static constexpr uint8_t	FRAME_MIN_SIZE = 9
	Minimum frame: CTRL0+CTRL1+DST(3)+SRC(3)+CMD(1).
static constexpr uint8_t	FRAME_MAX_DECLARED_SIZE = 32
	Largest frame length CTRL0's 5-bit length field (bits [4:0], length - 1) can express.
static constexpr uint8_t	FRAME_MAX_SIZE = FRAME_MAX_DECLARED_SIZE
	Historical name for FRAME_MAX_DECLARED_SIZE, kept as an alias rather than a second literal so the two names can never disagree — most call sites (set_cmd, serialize, parse, every fixed-size frame buffer that only ever holds a declared-length frame) predate the trailer/wire distinction and still read most naturally as "the max frame size".
static constexpr uint8_t	FRAME_MAX_DATA_SIZE = 23
	Maximum data bytes after command ID (declared length - header).
static constexpr uint8_t	FRAME_CMD_OFFSET = 8
	Byte offset of the command ID in a raw wire buffer.
static constexpr uint8_t	FRAME_CRC_SIZE = 2
	Size of the on-air CRC-CCITT trailer appended after every frame (declared bytes, plus the out-of-length MAC trailer when present).
static constexpr uint8_t	FRAME_MAX_TRAILER_SIZE = HMAC_SIZE
	Largest out-of-length authenticator a frame can carry.
static constexpr uint8_t	FRAME_MAX_WIRE_SIZE = FRAME_MAX_DECLARED_SIZE + FRAME_MAX_TRAILER_SIZE + FRAME_CRC_SIZE
	Largest number of bytes a buffer must hold to receive or transmit any frame this project knows about, trailer and CRC included: FRAME_MAX_DECLARED_SIZE (what CTRL0 can declare).
static constexpr uint32_t	FREQ_CH1 = 868250000
	The protocol uses 3 frequency channels in the 868 MHz ISM band.
static constexpr uint32_t	FREQ_CH2 = 868950000
	Channel 2: 868.95 MHz (1W and 2W, TX channel).
static constexpr uint32_t	FREQ_CH3 = 869850000
	Channel 3: 869.85 MHz (2W only).
static constexpr uint16_t	LONG_PREAMBLE = 1024
	Preamble is a sequence of 0xAA bytes that precedes every frame.
static constexpr uint16_t	SHORT_PREAMBLE = 8
	8 bytes for response/continuation frames
static constexpr uint16_t	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 broadcasting it across all 3 channels doesn't block the loop the way LONG_PREAMBLE does.
static constexpr uint16_t	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 uint16_t	PAIRING_DISCOVERY_PREAMBLE = LONG_PREAMBLE
	Default for TuningConfig::pairing_discovery_preamble — the preamble on the pairing discovery broadcast (CMD_DISCOVER_REQ/CMD_DISCOVER_ALT_REQ, 0x28/0x2E).
static constexpr uint32_t	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 int32_t	HOP_TIME_US = 2700
	Timing constants for frequency hopping and response waiting.
static constexpr int32_t	RESPONSE_WAIT_MS = 500
	Wait for response to non-start frame.
static constexpr int32_t	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	RESPONSE_AUTH_WAIT_MS
	Wait for final response after challenge response.
static constexpr int32_t	EXCHANGE_RETRY_DELAY_MS = 250
	Gap between retries within one HA command.
static constexpr uint8_t	EXCHANGE_RETRY_COUNT = 3
	Attempts per command before reporting failure.
static constexpr uint8_t	SCHEDULED_POLL_MAX_TRIES = 1
	Exchange tries for a status poll the scheduler owns — every status poll issued while StatusPollPolicy is tracking the device, which today is every status poll this component can produce (there is no user-facing "refresh status" button or action; if one is ever added, it must not take this branch).
static constexpr uint8_t	SCHEDULED_POLL_RETRY_GRACE_FIRST_FAILURE = 1
	Ladder positions at which a scheduler-owned status poll gets the full EXCHANGE_RETRY_COUNT back.
static constexpr uint8_t	SCHEDULED_POLL_RETRY_GRACE_LAST_FAILURE = 3
static constexpr uint16_t	EXCHANGE_TOTAL_BUDGET_MS = 2500
	Wall-clock ceiling on one whole exchange, retries included.
static constexpr uint8_t	ONEWAY_BURST_REPEATS = 4
	One-way (1W) transmit cadence.
static constexpr uint32_t	ONEWAY_BURST_INTERVAL_MS = 40
	Gap between those copies.
static constexpr int16_t	LBT_RSSI_THRESHOLD_DBM = -90
	Listen-before-talk (LBT) parameters for ETSI EN 300 220 compliance.
static constexpr uint8_t	LBT_MAX_RETRIES = 5
	Max carrier-sense attempts before TX anyway.
static constexpr uint8_t	LBT_RETRY_DELAY_MS = 5
	Backoff between LBT checks (≥ 5ms per ETSI).
static constexpr uint16_t	PAIRING_DISCOVERY_WAIT_MS = 2000
	Canonical defaults for the chip-neutral runtime-tunable pairing/discovery parameters.
static constexpr uint16_t	PAIRING_DISCOVERY_INITIAL_DWELL_MS = 300
	Dwell on CH2 before discovery hopping begins.
static constexpr uint8_t	PAIRING_KEY_EXCHANGE_RETRIES = 3
	Retries for the authenticated key-exchange phase.
constexpr uint8_t	RADIO_PACKET_BUFFER_SIZE
	Scratch buffer size for raw radio packets and recovered frames.
constexpr uint32_t	RX_HOP_HOLDOFF_US = 12000
	Longest a frame arriving on the current channel may hold off an idle-path channel hop, in microseconds.
static const char *const	TAG = "home_io_control.lr1121"
static constexpr uint16_t	LR1121_CMD_GET_STATUS = 0x0100
	cross-checked
static constexpr uint16_t	LR1121_CMD_GET_VERSION = 0x0101
	cross-checked
static constexpr uint16_t	LR1121_CMD_GET_ERRORS = 0x010D
	cross-checked (2-byte response)
static constexpr uint16_t	LR1121_CMD_CLEAR_ERRORS
	hardware-verified (called on every init/RX cycle, never rejected — see log_command_status_())
static constexpr uint16_t	LR1121_CMD_WRITE_BUFFER = 0x0109
	cross-checked
static constexpr uint16_t	LR1121_CMD_READ_BUFFER = 0x010A
	cross-checked
static constexpr uint16_t	LR1121_CMD_WRITE_REG_MEM_MASK32
	cross-checked (Semtech SWDR001 lr11xx_radio.c / RadioLib LR11x0_commands.h)
static constexpr uint16_t	LR1121_CMD_CALIBRATE = 0x010F
	cross-checked
static constexpr uint16_t	LR1121_CMD_CALIBRATE_IMAGE = 0x0111
	cross-checked (RadioLib calibrateImageRejection)
static constexpr uint16_t	LR1121_CMD_SET_DIO_AS_RF_SWITCH = 0x0112
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_DIO_IRQ_PARAMS = 0x0113
	cross-checked
static constexpr uint16_t	LR1121_CMD_CLEAR_IRQ = 0x0114
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_TCXO_MODE = 0x0117
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_STANDBY = 0x011C
	cross-checked
static constexpr uint16_t	LR1121_CMD_GET_RX_BUFFER_STATUS = 0x0203
	cross-checked
static constexpr uint16_t	LR1121_CMD_GET_PKT_STATUS
	cross-checked (Semtech SWDR001 lr11xx_radio.c :: lr11xx_radio_get_gfsk_pkt_status — 0 request params, 4-byte GFSK response: [rssi_sync, rssi_avg, rx_len, status_flags], rssi_sync/avg both decode via -(raw>>1) dBm, same formula as LR1121_CMD_GET_RSSI_INST)
static constexpr uint16_t	LR1121_CMD_GET_RSSI_INST = 0x0205
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_GFSK_SYNC_WORD = 0x0206
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_RX = 0x0209
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_TX = 0x020A
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_RF_FREQUENCY = 0x020B
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_PACKET_TYPE = 0x020E
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_MODULATION_PARAMS = 0x020F
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_PACKET_PARAMS = 0x0210
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_TX_PARAMS = 0x0211
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_RX_TX_FALLBACK_MODE = 0x0213
	cross-checked
static constexpr uint16_t	LR1121_CMD_SET_PA_CONFIG = 0x0215
	cross-checked
static constexpr uint32_t	LR1121_IRQ_TX_DONE = 1UL << 2
static constexpr uint32_t	LR1121_IRQ_RX_DONE = 1UL << 3
static constexpr uint32_t	LR1121_IRQ_PREAMBLE_DETECTED = 1UL << 4
static constexpr uint32_t	LR1121_IRQ_SYNC_WORD_VALID = 1UL << 5
static constexpr uint32_t	LR1121_IRQ_CRC_ERR = 1UL << 7
static constexpr uint32_t	LR1121_IRQ_TIMEOUT = 1UL << 10
static constexpr uint32_t	LR1121_IRQ_ACTIVITY_MASK
	IRQ bits that represent a terminal radio event — a frame finished decoding, an outbound frame completed, or the chip gave up on its own.
static constexpr uint32_t	LR1121_IRQ_DIO_ENABLE_MASK
	DIO-routed IRQ enable mask: TxDone|RxDone|PreambleDetected|SyncWordValid|Timeout.
static constexpr uint8_t	LR1121_DEVICE_TYPE = 0x03
	cross-checked against RadioLib and the datasheet
static constexpr uint8_t	LR1121_KNOWN_LATEST_FW_MAJOR = 0x01
	Newest LR1121 transceiver firmware known at the time this file was last updated, per the version-numbered filenames and CHANGELOG.md at https://github.com/Lora-net/radio_firmware_images/tree/master/lr1121/transceiver — the same two bytes GetVersion reports as fw_major/fw_minor (e.g.
static constexpr uint8_t	LR1121_KNOWN_LATEST_FW_MINOR = 0x04
static constexpr uint8_t	LR1121_PACKET_TYPE_GFSK = 0x01
	cross-checked against RadioLib
static constexpr uint8_t	LR1121_GFSK_CRC_OFF = 0x01
	cross-checked (same encoding as SX126x)
static constexpr uint8_t	LR1121_GFSK_PACKET_FIXED_LENGTH = 0x00
	cross-checked (same encoding as SX126x)
static constexpr uint8_t	LR1121_PREAMBLE_DETECTOR_16_BIT = 0x05
	Preamble detector length selector: 16 bits.
static constexpr uint8_t	LR1121_SYNC_WORD_PARAM_24_BITS = 0x18
	Sync word length: 24 bits, encoded as a literal bit count — cross-checked, identical encoding to SX1262's SX1262_SYNC_WORD_PARAM_24_BITS.
static constexpr uint8_t	LR1121_CALIBRATE_ALL_BLOCKS = 0x3F
	Calibrate "all blocks" bitmask.
static constexpr uint8_t	LR1121_FALLBACK_STDBY_XOSC = 0x02
	SetRxTxFallbackMode value for STDBY_XOSC.
static constexpr uint8_t	LR1121_RX_BUFFER_BASE = 0x00
	Offset a reception is written to in the LR1121's data buffer.
static constexpr uint32_t	LR1121_REG_HIGH_ACP_WORKAROUND_ADDR = 0x00F30054
	High-ACP (adjacent channel power) TX-quality erratum: clear bit 30 of this register before every SetRx/SetTx.
static constexpr uint32_t	LR1121_REG_HIGH_ACP_WORKAROUND_MASK = 1UL << 30
static constexpr uint32_t	LR1121_REG_HIGH_ACP_WORKAROUND_VALUE = 0x00000000
static constexpr uint32_t	LR1121_REG_GFSK_WORKAROUND_1_ADDR = 0x00F20344
	GFSK modulation workaround register trio, standard (non-0.6/1.2kbps) values for our 38.4kbps config — applied after every modulation-params write, mirroring RadioLib's workaroundGFSK() ("always the first step, even when resetting" per its own comment on the first write).
static constexpr uint32_t	LR1121_REG_GFSK_WORKAROUND_1_MASK = 0x00000030
static constexpr uint32_t	LR1121_REG_GFSK_WORKAROUND_1_VALUE = 0x00000010
static constexpr uint32_t	LR1121_REG_GFSK_WORKAROUND_2_ADDR = 0x00F20348
static constexpr uint32_t	LR1121_REG_GFSK_WORKAROUND_2_MASK = 0x00000005
static constexpr uint32_t	LR1121_REG_GFSK_WORKAROUND_2_VALUE = 0x00000001
static constexpr uint32_t	LR1121_REG_GFSK_WORKAROUND_3_ADDR = 0x00F20244
static constexpr uint32_t	LR1121_REG_GFSK_WORKAROUND_3_MASK = 0x0001FF03
static constexpr uint32_t	LR1121_REG_GFSK_WORKAROUND_3_VALUE = 0x00000A01
static constexpr uint8_t	LR1121_IMAGE_CAL_FREQ1 = 0xD7
	Banded image calibration for 868.25-869.85MHz +/-4MHz (~860-876MHz), matching RadioLib's setFrequency() margin.
static constexpr uint8_t	LR1121_IMAGE_CAL_FREQ2 = 0xDB
static constexpr uint8_t	LR1121_RFSWITCH_ENABLE_DIO5_DIO6 = 0x03
	DIO5 + DIO6 are switch pins.
static constexpr uint8_t	LR1121_RFSWITCH_STANDBY = 0x00
	Both low.
static constexpr uint8_t	LR1121_RFSWITCH_RX = 0x01
	DIO5 high.
static constexpr uint8_t	LR1121_RFSWITCH_TX = 0x02
	DIO6 high (both LP and HP PA).
static constexpr uint8_t	LR1121_RFSWITCH_TX_HP = 0x02
	Same as TX (LP PA only used today).
static constexpr uint8_t	LR1121_RFSWITCH_TX_HF = 0x00
	2.4GHz path unused; both low.
static constexpr uint8_t	LR1121_RFSWITCH_GNSS = 0x00
	Unused; both low.
static constexpr uint8_t	LR1121_RFSWITCH_WIFI = 0x00
	Unused; both low.
static constexpr uint32_t	LR1121_BUSY_TIMEOUT_MS = 3000
	How long SoftPhyDriverBase::wait_busy_() waits for BUSY to drop before declaring the chip failed.
static constexpr uint8_t	LR1121_TCXO_STARTUP_DELAY_TICKS_MSB = 0x00
	LR1121 TCXO voltage on the T3-S3 board — 3.0V, confirmed on real hardware.
static constexpr uint8_t	LR1121_TCXO_STARTUP_DELAY_TICKS_MID = 0x01
static constexpr uint8_t	LR1121_TCXO_STARTUP_DELAY_TICKS_LSB = 0x40
	0x140 ticks at 30.52us/tick (32.768kHz RTC) is ~9.8ms (the SX1262's tick base differs, so the same tick count means a different time there) — harmless either way, since a longer startup is safe.
static const uint8_t	UART_PROBE_MAX_BIT_OFFSET = 10
	Maximum bit offset to search for valid UART decode start position.
static constexpr uint8_t	UART_CELL_BITS = 10
	Bits an on-air UART cell spends per protocol byte: start(1) + data(8) + stop(1).
static const char *const	TAG = "home_io_control.soft_phy"
static constexpr uint8_t	SOFT_PHY_RX_PROBE_PACKET_LEN = 48
	Fixed raw-RX probe length: chosen from captures of 23-25 byte protocol frames after UART packing and CRC appending — the longest frame (25 bytes + 2 CRC) UART-packs to 34 raw bytes, so 48 bytes preserves complete traffic (with margin for leading noise before the frame start) without relying on either chip's variable-length engine.
static constexpr uint32_t	SOFT_PHY_ALL_IRQ_BITS = 0xFFFFFFFF
	Sentinel meaning "every IRQ bit counts as activity" — the default for SoftPhyDriverBase::activity_irq_mask.
static constexpr uint8_t	SOFT_PHY_EARLY_HEADER_RAW_BYTES = 3
	Raw bytes read in the first stage of a length-driven receive — enough to hold CTRL0's UART cell (10 bits) at any of the probe's bit alignments (up to 9 bits of slack).
static constexpr uint8_t	SOFT_PHY_EARLY_READ_MARGIN_BYTES = 2
	Air-time margin added before every mid-reception buffer read, in raw bytes.
static constexpr uint32_t	SOFT_PHY_EARLY_POLL_US = 100
	Poll interval while waiting out a frame's remaining air time, in microseconds.
static constexpr uint32_t	SOFT_PHY_EARLY_MIN_WINDOW_MS = 12
	Smallest receive window a length-driven receive will be attempted in, in milliseconds.
static constexpr uint32_t	SOFT_PHY_IDLE_RX_COMPLETION_BUDGET_MS = 20
	Blocking budget SoftPhyDriverBase::check_for_packet gives a length-driven receive, in milliseconds — the timeout_ms passed to try_early_completion_() from the non-blocking idle-loop RX path (issue #81).
static constexpr uint32_t	SOFT_PHY_LINE_RATE_BPS = 38400
	Protocol line rate. The same 38400 bps every driver programs into its own bitrate register.
static constexpr uint32_t	SOFT_PHY_US_PER_SECOND = 1000000
	Microseconds in a second, for the air-time arithmetic below.
static const char *const	TAG = "home_io_control.sx1262"
static const uint8_t	SX1262_SYNC_WORD_PARAM_24_BITS = 0x18
static constexpr uint8_t	SX1262_SET_STANDBY = 0x80
static constexpr uint8_t	SX1262_SET_RX = 0x82
static constexpr uint8_t	SX1262_SET_TX = 0x83
static constexpr uint8_t	SX1262_SET_RF_FREQUENCY = 0x86
static constexpr uint8_t	SX1262_SET_RX_TX_FALLBACK_MODE = 0x93
static constexpr uint8_t	SX1262_WRITE_BUFFER = 0x0E
static constexpr uint8_t	SX1262_READ_BUFFER = 0x1E
static constexpr uint8_t	SX1262_SET_DIO_IRQ_PARAMS = 0x08
static constexpr uint8_t	SX1262_GET_IRQ_STATUS = 0x12
static constexpr uint8_t	SX1262_GET_PACKET_STATUS = 0x14
static constexpr uint8_t	SX1262_GET_DEVICE_ERRORS = 0x17
static constexpr uint8_t	SX1262_CLEAR_IRQ_STATUS = 0x02
static constexpr uint8_t	SX1262_CLEAR_DEVICE_ERRORS = 0x07
static constexpr uint8_t	SX1262_SET_PACKET_TYPE = 0x8A
static constexpr uint8_t	SX1262_SET_MODULATION_PARAMS = 0x8B
static constexpr uint8_t	SX1262_SET_PACKET_PARAMS = 0x8C
static constexpr uint8_t	SX1262_SET_BUFFER_BASE_ADDRESS = 0x8F
static constexpr uint8_t	SX1262_SET_PA_CONFIG = 0x95
static constexpr uint8_t	SX1262_SET_TX_PARAMS = 0x8E
static constexpr uint8_t	SX1262_SET_DIO2_AS_RF_SWITCH_CTRL = 0x9D
static constexpr uint8_t	SX1262_SET_DIO3_AS_TCXO_CTRL = 0x97
static constexpr uint8_t	SX1262_CALIBRATE = 0x89
static constexpr uint8_t	SX1262_CALIBRATE_IMAGE = 0x98
static constexpr uint8_t	SX1262_GET_RX_BUFFER_STATUS = 0x13
static constexpr uint8_t	SX1262_GET_RSSI_INST = 0x15
static constexpr uint8_t	SX1262_SET_REGULATOR_MODE = 0x96
static constexpr uint8_t	SX1262_GET_STATUS = 0xC0
static constexpr uint8_t	SX1262_WRITE_REGISTER = 0x0D
static constexpr uint8_t	SX1262_READ_REGISTER = 0x1D
static constexpr uint16_t	SX1262_IRQ_TX_DONE = 0x0001
static constexpr uint16_t	SX1262_IRQ_RX_DONE = 0x0002
static constexpr uint16_t	SX1262_IRQ_PREAMBLE_DETECTED = 0x0004
static constexpr uint16_t	SX1262_IRQ_SYNC_WORD_VALID = 0x0008
static constexpr uint16_t	SX1262_IRQ_CRC_ERR = 0x0040
static constexpr uint16_t	SX1262_IRQ_ACTIVITY_MASK
	IRQ bits that represent a terminal radio event — a frame finished decoding, an outbound frame completed, or the chip reported a bad CRC.
static constexpr uint16_t	SX1262_REG_SYNC_WORD = 0x06C0
static constexpr uint16_t	SX1262_REG_RX_GAIN = 0x08AC
static constexpr uint16_t	SX1262_REG_TX_CLAMP_CONFIG = 0x08D8
static constexpr uint16_t	SX1262_REG_TX_MODULATION = 0x0889
	TX modulation-quality erratum register (SX1262 datasheet §15.1, "Modulation Quality with 500 kHz LoRa Bandwidth" — the title names LoRa, but the workaround table covers every modulation).
static constexpr uint8_t	SX1262_TX_MODULATION_GFSK_BIT = 0x04
	Bit 2 of SX1262_REG_TX_MODULATION — the (G)FSK-correct value is 1.
static constexpr uint8_t	SX1262_TX_BUFFER_BASE = 0x00
	Data-buffer split programmed by configure_buffer_base(): TX packets build from 0x00, RX packets land at 0x80.
static constexpr uint8_t	SX1262_RX_BUFFER_BASE = 0x80
static constexpr uint8_t	SX1262_GFSK_PACKET_TYPE_KNOWN_LENGTH = 0x00
static constexpr uint8_t	SX1262_GFSK_CRC_OFF = 0x01
static constexpr uint8_t	SX1262_FALLBACK_STDBY_XOSC = 0x30
static constexpr uint32_t	SX1262_BUSY_TIMEOUT_MS = 10
	How long SoftPhyDriverBase::wait_busy_() waits for BUSY to drop before declaring the chip failed.
static const char *const	TAG = "home_io_control.sx1276"
static constexpr uint8_t	REG_FIFO = 0x00
	FIFO read/write access.
static constexpr uint8_t	REG_OP_MODE = 0x01
	Operating mode (sleep/standby/tx/rx).
static constexpr uint8_t	REG_BITRATE_MSB = 0x02
	Bit rate MSB = FXOSC / bitrate.
static constexpr uint8_t	REG_BITRATE_LSB = 0x03
static constexpr uint8_t	REG_FDEV_MSB = 0x04
	Frequency deviation MSB.
static constexpr uint8_t	REG_FDEV_LSB = 0x05
static constexpr uint8_t	REG_FRF_MSB = 0x06
	Carrier frequency MSB (freq = FRF * FXOSC / 2^19).
static constexpr uint8_t	REG_FRF_MID = 0x07
static constexpr uint8_t	REG_FRF_LSB = 0x08
static constexpr uint8_t	REG_PA_CONFIG = 0x09
	Power amplifier config (pin select + power level).
static constexpr uint8_t	REG_PA_RAMP = 0x0A
	PA ramp time and modulation shaping.
static constexpr uint8_t	REG_LNA = 0x0C
	Low noise amplifier gain and boost.
static constexpr uint8_t	REG_RX_CONFIG = 0x0D
	Receiver configuration (AFC, AGC, trigger).
static constexpr uint8_t	REG_RSSI_CONFIG = 0x0E
	RSSI smoothing.
static constexpr uint8_t	REG_RX_BW = 0x12
	Receiver bandwidth.
static constexpr uint8_t	REG_AFC_BW = 0x13
	AFC bandwidth.
static constexpr uint8_t	REG_AFC_FEI = 0x1A
	AFC auto clear.
static constexpr uint8_t	REG_PREAMBLE_DETECT = 0x1F
	Preamble detector config.
static constexpr uint8_t	REG_OSC = 0x24
	Oscillator / clock output.
static constexpr uint8_t	REG_RSSI_VALUE = 0x11
	Instant RSSI value in FSK mode.
static constexpr uint8_t	REG_PREAMBLE_MSB = 0x25
	TX preamble length MSB.
static constexpr uint8_t	REG_PREAMBLE_LSB = 0x26
static constexpr uint8_t	REG_SYNC_CONFIG = 0x27
	Sync word config (size, polarity, enable).
static constexpr uint8_t	REG_SYNC_VALUE1 = 0x28
	Sync word byte 1 (registers 0x28-0x2F for bytes 1-8).
static constexpr uint8_t	REG_PACKET_CONFIG1 = 0x30
	Packet format, CRC, encoding.
static constexpr uint8_t	REG_PACKET_CONFIG2 = 0x31
	Packet mode, IoHomeOn, PowerFrame.
static constexpr uint8_t	REG_PAYLOAD_LENGTH = 0x32
	Max payload length.
static constexpr uint8_t	REG_FIFO_THRESH = 0x35
	FIFO threshold for TX start condition.
static constexpr uint8_t	REG_IRQ_FLAGS1 = 0x3E
	IRQ flags: mode ready, preamble detect, etc.
static constexpr uint8_t	REG_IRQ_FLAGS2 = 0x3F
	IRQ flags: FIFO full/empty, payload ready, CRC ok.
static constexpr uint8_t	REG_DIO_MAPPING1 = 0x40
	DIO0-DIO3 pin mapping.
static constexpr uint8_t	REG_DIO_MAPPING2 = 0x41
	DIO4-DIO5 pin mapping.
static constexpr uint8_t	REG_VERSION = 0x42
	Chip version (should read 0x12 for SX1276).
static constexpr uint8_t	REG_PLLHOP = 0x44
	PLL hop: fast frequency change without standby.
static constexpr uint8_t	REG_IMAGE_CAL = 0x3B
	Image calibration.
static constexpr uint8_t	MODE_SLEEP = 0x00
static constexpr uint8_t	MODE_STDBY = 0x01
static constexpr uint8_t	MODE_TX = 0x03
static constexpr uint8_t	MODE_RX = 0x05
static constexpr uint8_t	MODE_MASK = 0x07
static constexpr uint32_t	FXOSC = 32000000U
	SX1276 crystal oscillator frequency (32 MHz).
static constexpr uint32_t	MAX_TRACKED_STATUS_POLL_WINDOW_MS = 600000
	Hard stop for bounded follow-up polling after a command or remote activity.
static constexpr uint32_t	INITIAL_STATUS_REQUEST_DELAY_MS = 5000
	Delay before the first post-boot status request from an entity.
static constexpr uint32_t	REMOTE_ACTIVITY_STATUS_POLL_DELAY_MS = 2000
	Delay before polling after overheard remote traffic.
static constexpr uint32_t	ONEWAY_QUIET_PERIOD_MS = 700
	Hold queued background polls back for this long after any 1W frame, so a poll the hub itself scheduled does not occupy the (half-duplex) radio while the remote is still transmitting.
static constexpr uint32_t	ONEWAY_POLL_DEFER_CAP_MS = 5000
	Hard cap on how long sustained 1W traffic may hold a background poll back in total, measured from the start of the burst rather than the most recent frame.
static constexpr uint32_t	DEFAULT_SETTLE_POLL_DELAY_MS = 3000
	Default follow-up settle-poll delay used while a device may still be moving, when no explicit poll interval is configured (interval_ms == 0).
static constexpr uint32_t	STOP_SETTLE_POLL_CAP_MS = 1000
	Upper bound on the settle-poll delay after a STOP command.
static constexpr uint16_t	SX1262_RESPONSE_PREAMBLE = 8
	SX1262-specific preamble for response/continuation frames within an exchange.
static constexpr uint16_t	SX1262_POST_TX_SETTLE_US = 500
	SX1262-specific post-TX settling delay before re-entering RX.
static constexpr uint16_t	SX1276_RESPONSE_PREAMBLE = 12
	SX1276 preamble for response/continuation frames within an exchange.
static constexpr uint16_t	SX1276_DISCOVERY_HOP_SLICE_MS = 5
	Per-channel dwell while SX1276 pairing discovery hops across channels.
static constexpr uint16_t	SX1262_DISCOVERY_HOP_SLICE_MS = 7
	Per-channel dwell while SX1262 pairing discovery hops across channels.
static constexpr uint16_t	LR1121_RESPONSE_PREAMBLE = SX1262_RESPONSE_PREAMBLE
	LR1121-specific preamble for response/continuation frames within an exchange.
static constexpr uint16_t	LR1121_POST_TX_SETTLE_US = SX1262_POST_TX_SETTLE_US
	LR1121-specific post-TX settling delay before re-entering RX.
static constexpr uint16_t	LR1121_DISCOVERY_HOP_SLICE_MS = 7
	Per-channel dwell while LR1121 pairing discovery hops across channels.
static constexpr TuningNumberParam	NUMBER_PARAMS []
static constexpr TuningSelectParam	SELECT_PARAMS []
Pairing timing constants
Timeouts and retry limits for the pairing flow's blocking waits.
constexpr uint32_t	PAIRING_DISCOVERY_RESPONSE_TIMEOUT_MS = 2000
	Discovery wait window after sending 0x28.
constexpr uint8_t	PAIRING_DISCOVERY_MAX_ATTEMPTS = 3
	Retry discovery TX up to this many times.
constexpr uint32_t	PAIRING_KEY_CHALLENGE_TIMEOUT_MS = 500
	Wait window for the device's 0x3C challenge.
constexpr uint32_t	PAIRING_KEY_CONFIRM_TIMEOUT_MS = 500
	Wait for 0x33 key confirm after sending 0x32.
constexpr uint32_t	PAIRING_RECENT_ONE_WAY_SIGHTING_WINDOW_MS = 15000
	How recent a RecentOneWayPairingSighting has to be, relative to discover_and_pair() starting, to still count as evidence for this attempt.
static constexpr uint8_t	ADDRESS_SUFFIX_MASK = 0x3F
	Well-known address suffix values in the broadcast address space.
static constexpr uint8_t	ADDRESS_SUFFIX_BROADCAST = 0x3F
	Suffix for "all devices of this type" broadcast.
static constexpr uint8_t	ADDRESS_SUFFIX_DISCOVERY = 0x3B
	Suffix for discovery-related broadcasts.
static constexpr uint8_t	MANUFACTURER_VELUX = 1
	IO-Homecontrol manufacturer ID constants.
static constexpr uint8_t	MANUFACTURER_SOMFY = 2
	Somfy (shutters, awnings, blinds).
static constexpr uint8_t	MANUFACTURER_HONEYWELL = 3
	Honeywell.
static constexpr uint8_t	MANUFACTURER_HORMANN = 4
	Hörmann (garage doors, gates).
static constexpr uint8_t	MANUFACTURER_ASSA_ABLOY = 5
	ASSA ABLOY (locks, access).
static constexpr uint8_t	MANUFACTURER_NIKO = 6
	Niko (switches, home automation).
static constexpr uint8_t	MANUFACTURER_WINDOW_MASTER = 7
	WINDOW MASTER (ventilation).
static constexpr uint8_t	MANUFACTURER_RENSON = 8
	Renson (ventilation, sun protection).
static constexpr uint8_t	MANUFACTURER_CIAT = 9
	CIAT (HVAC).
static constexpr uint8_t	MANUFACTURER_SECUYOU = 10
	Secuyou (security).
static constexpr uint8_t	MANUFACTURER_OVERKIZ = 11
	OVERKIZ (Somfy connectivity platform).
static constexpr uint8_t	MANUFACTURER_ATLANTIC_GROUP = 12
	Atlantic Group (heating, hot water).
static constexpr uint8_t	ORIGINATOR_LOCAL_USER = 0x00
	Command originator codes indicating what or who triggered a command.
static constexpr uint8_t	ORIGINATOR_USER_REMOTE = 0x01
	User sent command from a remote control.
static constexpr uint8_t	ORIGINATOR_RAIN_SENSOR = 0x02
	Rain sensor triggered the movement.
static constexpr uint8_t	ORIGINATOR_TIMER = 0x03
	Timer or schedule triggered the movement.
static constexpr uint8_t	ORIGINATOR_SECURITY = 0x04
	Security controlling device (SCD) action.
static constexpr uint8_t	ORIGINATOR_UPS = 0x05
	Uninterruptible power supply action.
static constexpr uint8_t	ORIGINATOR_SMART_CONTROLLER = 0x06
	Smart function controller.
static constexpr uint8_t	ORIGINATOR_LIFESTYLE = 0x07
	Lifestyle scenario controller.
static constexpr uint8_t	ORIGINATOR_SAAC = 0x08
	Stand-alone automatic controller (SAAC).
static constexpr uint8_t	ORIGINATOR_WIND_SENSOR = 0x09
	Wind sensor triggered the movement.
static constexpr uint8_t	ORIGINATOR_LOAD_SHEDDING = 0x0B
	Load-shedding manager.
static constexpr uint8_t	ORIGINATOR_LOCAL_LIGHT = 0x0C
	Local light sensor.
static constexpr uint8_t	ORIGINATOR_ENVIRONMENT = 0x0D
	Unspecified environment sensor.
static constexpr uint8_t	ORIGINATOR_MYSELF = 0x10
	Actuator decided to move by itself.
static constexpr uint8_t	ORIGINATOR_AUTOMATIC_CYCLE = 0xFE
	Automatic cycle / external access.
static constexpr uint8_t	ORIGINATOR_EMERGENCY = 0xFF
	Emergency command (never disabled).
static constexpr uint8_t	ACEI_VALID_BIT = 0x01
	ACEI byte bit-field definitions.
static constexpr uint8_t	ACEI_EXTENDED_MASK = 0x06
	Bits [2:1]: extended field.
static constexpr uint8_t	ACEI_EXTENDED_SHIFT = 1
	Shift for extended field extraction.
static constexpr uint8_t	ACEI_SERVICE_MASK = 0x18
	Bits [4:3]: service type.
static constexpr uint8_t	ACEI_SERVICE_SHIFT = 3
	Shift for service field extraction.
static constexpr uint8_t	ACEI_LEVEL_MASK = 0xE0
	Bits [7:5]: priority level (0–7).
static constexpr uint8_t	ACEI_LEVEL_SHIFT = 5
	Shift for priority level extraction.
static constexpr uint8_t	ACEI_LEVEL_PROTECTION_HUMAN = 0
	ACEI priority level values (0–7).
static constexpr uint8_t	ACEI_LEVEL_PROTECTION_SENSOR = 1
	Goods/environment protection via sensors.
static constexpr uint8_t	ACEI_LEVEL_USER_HIGH = 2
	High-priority user controller.
static constexpr uint8_t	ACEI_LEVEL_USER_DEFAULT = 3
	Default remote controller priority.
static constexpr uint8_t	ACEI_LEVEL_COMFORT_1 = 4
	Comfort automation level 1.
static constexpr uint8_t	ACEI_LEVEL_COMFORT_2 = 5
	Comfort automation level 2.
static constexpr uint8_t	ACEI_LEVEL_AUTO_SAAC = 6
	Stand-alone automatic controller.
static constexpr uint8_t	ACEI_LEVEL_AUTO_DEFAULT = 7
	Default automatic level (lowest).
static constexpr uint8_t	DISCOVERY_RESP_BACKBONE_OFFSET = 2
	Byte offsets within CMD_DISCOVER_RESP (0x29) payload data.
static constexpr uint8_t	DISCOVERY_RESP_MANUFACTURER_OFFSET = 5
	Manufacturer ID at data[5].
static constexpr uint8_t	DISCOVERY_RESP_FLAGS_OFFSET = 6
	Flags byte at data[6].
static constexpr uint8_t	DISCOVERY_RESP_TIMESTAMP_OFFSET = 7
	Timestamp starts at data[7] (2 bytes).
static constexpr uint8_t	DISCOVERY_RESP_FULL_SIZE = 9
	Full discovery response payload size.
static constexpr uint8_t	DISCOVERY_FLAGS_ATT_MASK = 0xC0
	Bit masks and shifts for the Multi Information Byte fields.
static constexpr uint8_t	DISCOVERY_FLAGS_ATT_SHIFT = 6
	Shift for ATT field extraction.
static constexpr uint8_t	DISCOVERY_FLAGS_SYNC_CTRL_GRP = 0x20
	Bit 5: supports sync control group.
static constexpr uint8_t	DISCOVERY_FLAGS_RF_SUPPORT = 0x08
	Bit 3: RF support in node (0=yes, 1=no).
static constexpr uint8_t	DISCOVERY_FLAGS_POWER_SAVE_MASK = 0x03
	Bits [1:0]: power save mode.
static constexpr uint8_t	ATT_CLASS_5S = 0
	Actuator Turnaround Time (ATT) class values.
static constexpr uint8_t	ATT_CLASS_10S = 1
	Response within 10 seconds.
static constexpr uint8_t	ATT_CLASS_20S = 2
	Response within 20 seconds.
static constexpr uint8_t	ATT_CLASS_40S = 3
	Response within 40 seconds.
static constexpr uint8_t	POWER_SAVE_ALWAYS_ALIVE = 0
	Power save mode values from the Multi Information Byte.
static constexpr uint8_t	POWER_SAVE_LOW_POWER = 1
	Device sleeps — needs long preamble to wake.
Background-poll retry delays after silent failures (no reply received)
static constexpr uint32_t	STATUS_RETRY_AFTER_FAIL_MS = 5000
	First retry after a silent failure.
static constexpr uint32_t	STATUS_RETRY_AFTER_FAIL_STEP2_MS = 15000
	Second retry after a silent failure.
static constexpr uint32_t	STATUS_RETRY_AFTER_FAIL_STEP3_MS = 30000
	Third retry after a silent failure.
static constexpr uint32_t	STATUS_RETRY_AFTER_FAIL_STEP4_MS = 60000
	Fourth retry after a silent failure.
static constexpr uint32_t	STATUS_RETRY_AFTER_FAIL_MAX_MS
	Steady-state backoff after many silent failures.
Background-poll retry delays after auth-shaped failures (0x3C challenge seen)
static constexpr uint32_t	STATUS_AUTH_RETRY_AFTER_FAIL_MS = 30000
	First retry after a challenge-seen failure.
static constexpr uint32_t	STATUS_AUTH_RETRY_AFTER_FAIL_STEP2_MS = 120000
	Second retry.
static constexpr uint32_t	STATUS_AUTH_RETRY_AFTER_FAIL_MAX_MS = 300000
	Steady-state after repeated auth failures.

Typedef Documentation

BeginBlockingExcursionFn

using esphome::home_io_control::BeginBlockingExcursionFn = std::function<void()>

Raises the hub's "operation took a long time" warning threshold for a blocking radio excursion — writes Component::warn_if_blocking_over_, which is protected on ESPHome's Component.

Wired to a lambda in the hub's initializer list, which has protected access.

Definition at line 39 of file hub_hooks.h.

DeviceUpdateCallback

using esphome::home_io_control::DeviceUpdateCallback = std::function<void(const std::string &device_id, const IoDevice &device)>

Callback type invoked when a device's state changes.

Definition at line 23 of file device_registry.h.

NamedTimeoutFn

using esphome::home_io_control::NamedTimeoutFn = std::function<void(const char *name, uint32_t delay_ms, std::function<void()> callback)>

Schedules a named, replace-on-same-name timeout on the hub's ESPHome scheduler.

Parameters

name	Timer name; a later call with the same name replaces the pending callback.
delay_ms	Delay before the callback runs.
callback	Work to run in loop() context after the delay.

Definition at line 27 of file hub_hooks.h.

OneWayCommandReportFn

using esphome::home_io_control::OneWayCommandReportFn = std::function<void(const OneWayCommandReport &report)>

Invoked once per attempted 1W command, successful or not.

Definition at line 53 of file oneway_transmitter.h.

OneWayTransmitFn

using esphome::home_io_control::OneWayTransmitFn = std::function<bool(const IoFrame &frame, uint32_t freq, uint16_t preamble)>

How the transmitter puts a frame on air.

Injected rather than taken as a collaborator reference so this class depends on the ability to transmit rather than on whichever object currently owns the radio. The hub wires it to its own transmit_frame_; a test wires it to a recorder and needs no radio at all.

Parameters

frame	Frame to serialize and transmit.
freq	RF channel frequency in Hz.
preamble	Preamble length in bytes.

Returns

true if the frame reached the radio.

Definition at line 35 of file oneway_transmitter.h.

ReplyHandler

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.

Parameters

parsed	Points at the caller's own output frame, already filled by parse(); nullptr when parse() rejected the packet (the exchange waits log that case, the pairing waits do not).
packet	The raw packet, for length/frequency logging.

Returns

What the listen should do next — see ReplyDisposition.

Keep captures to a few pointers: small callables avoid std::function's heap fallback on the implementations this project builds against.

Definition at line 136 of file hub_exchange.h.

TransmitFrameFn

using esphome::home_io_control::TransmitFrameFn = std::function<bool(const IoFrame &frame, uint32_t freq_hz, uint16_t preamble)>

Puts a frame on air on a given channel via the hub's protected transmit_frame_().

Parameters

frame	Frame to serialize and transmit.
freq_hz	RF channel frequency in Hz.
preamble	Preamble length in bytes.

Returns

true if the frame reached the radio.

Definition at line 34 of file hub_hooks.h.

Enumeration Type Documentation

AddressClass

enum class esphome::home_io_control::AddressClass : uint8_t

strong

Address classification categories for diagnostic purposes.

IO-Homecontrol uses the target address field to encode both unicast device addresses and broadcast targets. The first byte being 0x00 indicates a broadcast; the remaining bytes encode the target device type.

Enumerator
UNICAST	Normal device-to-device unicast address (first byte != 0x00).
BROADCAST_ALL	Broadcast to all devices of a type (address suffix 0x3F).
BROADCAST_TYPE	Broadcast to specific device type with non-standard suffix.
DISCOVERY	Discovery-related broadcast (address suffix 0x3B).
UNKNOWN_BROADCAST	Broadcast pattern that does not match known suffixes.

Definition at line 95 of file proto_codecs.h.

BootloaderMismatch

enum class esphome::home_io_control::BootloaderMismatch : uint8_t

strong

Direction of a bootloader/target mismatch, for messaging.

lr1121_flash_decision()'s REJECT_BOOTLOADER_TOO_OLD verdict fires whenever lr1121_bootloader_supports_target() returns UNSUPPORTED, which covers both directions: the target needs a newer bootloader than this chip has (the only direction reachable before the bootloader-update feature existed), and the target needs an OLDER bootloader than this chip has – a downgrade, unreachable until a chip can actually be running 0x2101. Used for messaging only, in both the transceiver-only and bootloader-update builds – it never changes lr1121_flash_decision()'s own verdict.

Enumerator
NONE	target_fw is unknown, or its required bootloader matches bootloader_version.
TARGET_NEEDS_NEWER	The "too old" direction – what REJECT_BOOTLOADER_TOO_OLD has always meant until now.
TARGET_NEEDS_OLDER	The "too new" direction – a downgrade, newly reachable once this feature ships.

Definition at line 155 of file lr1121_firmware_decisions.h.

BootloaderSupport

enum class esphome::home_io_control::BootloaderSupport : uint8_t

strong

Whether a target firmware version is known to work with a given bootloader version.

Enumerator
SUPPORTED	Both versions known, and the pairing is in LR1121_KNOWN_BOOTLOADER_REQUIREMENTS.
UNSUPPORTED	target_fw is known, but not paired with this bootloader_version.
UNKNOWN_TARGET	target_fw does not appear in LR1121_KNOWN_BOOTLOADER_REQUIREMENTS at all.

Definition at line 111 of file lr1121_firmware_decisions.h.

BootloaderUpgradePath

enum class esphome::home_io_control::BootloaderUpgradePath : uint8_t

strong

Whether the three-stage bootloader-rewrite sequence (ADR 0021) is applicable, and if not, why.

Enumerator
NOT_APPLICABLE	No block, or no upgrade needed/possible to evaluate. Keep the original verdict.
AVAILABLE	Three-stage is possible. Still requires the arming switch to actually run.
BLOCKED_UNKNOWN_TARGET	Block present, but this build cannot know what the target needs.
BLOCKED_BOOTLOADER_NEWER	Target needs an OLDER bootloader. Not reachable today, likely never.

Definition at line 173 of file lr1121_firmware_decisions.h.

CoverCommand

enum class esphome::home_io_control::CoverCommand : uint8_t

strong

Named device commands for cover-type actuators.

These represent the discrete non-positional actions a controller can send to a cover device. Each maps to a specific wire encoding in the CMD_EXECUTE payload. Using this enum avoids conflating numeric positions (0–100) with command codes.

Enumerator
STOP	Stop movement immediately.
FAVORITE	Move to stored favorite/"My" position.
VENT	Move to ventilation position (window-type devices).
FORCE_OPEN	Move to fully open at elevated priority; intended to bypass soft locks and environmental limits (confirmed on real hardware to move correctly; bypassing an active lock is still unconfirmed — see create_force_open() in proto_commands.cpp).

Definition at line 215 of file proto_device_model.h.

DeviceCapabilityClass

enum class esphome::home_io_control::DeviceCapabilityClass : uint8_t

strong

High‑level capability class derived from DeviceType.

Enumerator
UNKNOWN	Unknown capability.
COVER	Position‑controlled cover (shutter/blind/awning).
LIGHT	Binary on/off light.
SWITCH	Binary on/off switch.
SENSOR	Sensor device.
BEACON	Beacon.
CLIMATE	Climate device (heating/cooling).
LOCK	Lock.

Definition at line 61 of file proto_device_model.h.

DeviceNameValidationError

enum class esphome::home_io_control::DeviceNameValidationError : uint8_t

strong

Validation result for outbound device-name writes.

Enumerator
NONE	Name is valid and encodable.
EMPTY	Name is empty after normalization.
TOO_LONG	Name exceeds the 15-character write limit.
INVALID_UTF8	Name contains malformed UTF-8 bytes.
UNSUPPORTED_CHAR	Name contains characters outside Latin-1.

Definition at line 34 of file proto_codecs.h.

DeviceType

enum class esphome::home_io_control::DeviceType : uint8_t

strong

Device type identifiers reported by IO‑Homecontrol products.

The numeric values follow the official specification. Do not reassign or reorder these.

Enumerator
UNKNOWN	Unknown/unspecified device.
VENETIAN_BLIND	Venetian blind.
ROLLER_SHUTTER	Roller shutter.
AWNING	Awning.
WINDOW_OPENER	Window opening actuator.
GARAGE_OPENER	Garage door opener.
LIGHT	Binary light.
GATE_OPENER	Gate opener.
ROLLING_DOOR_OPENER	Rolling door opener.
LOCK	Lock.
BLIND	Generic blind.
SCREEN	Insect/privacy screen.
BEACON	Beacon (unpaired/announcement). Not YAML-selectable: a discovery pseudo-type, not a configurable actuator. Allowlisted in device_type_sync_test.cpp.
DUAL_SHUTTER	Dual-section shutter.
HEATING_TEMPERATURE_INTERFACE	Heating temperature interface.
ON_OFF_SWITCH	Generic on/off switch.
HORIZONTAL_AWNING	Horizontal awning (open/close inverted).
EXTERNAL_VENETIAN_BLIND	External venetian blind.
LOUVRE_BLIND	Louvre blind.
CURTAIN_TRACK	Curtain track.
VENTILATION_POINT	Ventilation point.
EXTERIOR_HEATING	Exterior heating.
HEAT_PUMP	Heat pump.
INTRUSION_ALARM	Intrusion alarm.
SWINGING_SHUTTER	Swinging shutter.

Definition at line 25 of file proto_device_model.h.

DiscoveryCommand

enum class esphome::home_io_control::DiscoveryCommand : uint8_t

strong

Discovery request command codes.

Enumerator
DISCOVER	Standard broadcast discovery request (to 0x00003B).
DISCOVER_SPE	SPE roll-call request (self-authenticating; see CMD_DISCOVER_SPE_REQ). Deliberately not offered as a pairing_discovery_commands preset in tuning.py: only devices that already hold the system key answer it, so it can never help reach a device in learning mode. Retained here because the command byte is still needed to send a roll-call, and because discovery_command_from_string() stays permissive enough to parse it — do not remove either as dead code.
DISCOVER_ALT	Alternate broadcast discovery (to 0x00003F), with optional payload byte.

Definition at line 73 of file tuning_config.h.

EnrollGesture

enum class esphome::home_io_control::EnrollGesture : uint8_t

strong

Which 1W enrollment gesture a manufacturer's actuators expect.

SOMFY: one 0x30 add-controller burst to the identity's own io_device_type (the shape this project has hardware-validated). VELUX_KLI: a 0x39 clear to the all-devices address, then a 0x30 burst to each class in OneWayWireProfile::enrollment_classes, then a STOP+DOWN EXECUTE follow-up — the gesture a real KLI 310/313 PROG press produces (issue #74 capture + samr037/iohc-flipper tx_runner.c + the KLI manual). See ADR 0032.

Enumerator
SOMFY
VELUX_KLI

Definition at line 84 of file oneway_controller.h.

ExchangeOutcome

enum class esphome::home_io_control::ExchangeOutcome : uint8_t

strong

Authenticated exchange engine — outbound and inbound protocol flows.

All timing constants (retry count/delay, response windows) come from proto_timing.h; per-chip dwell overrides are queried from the RadioDriver.

What an outbound exchange actually achieved.

Deliberately not a bool: "the device accepted the command" and "the device told us what happened" are different facts, and some devices only ever deliver the first.

Some devices challenge a command, authenticate it, execute it, and then transmit nothing for several seconds — up to a dozen — reporting via an asynchronous status update later instead of closing the exchange with a synchronous reply, all well outside the exchange's own response window. Other devices on the same protocol close the exchange properly with a synchronous 0x04 (see tests/corpus/captures/exchange/somfy_awning_exchange_open_sx1276.yaml), so the four-frame exchange is real — just not universal, and a caller cannot assume either shape from the command alone.

SUCCESS_UNCONFIRMED exists so that silence after a real authentication is not treated the same as a request the device may never have heard at all: the two need different retry rules (see decisions::retry_after_unconfirmed_accept_is_safe()) and different reporting to the caller.

Enumerator
FAILED	No usable reply; the device may never have heard the request.
SUCCESS_WITH_RESPONSE	Device replied; the caller's response frame is populated.
SUCCESS_UNCONFIRMED	Device authenticated the request — so it received and accepted it — but sent no final response. response is NOT populated. Callers that need payload (key exchange) must treat this as failure; callers that only need "the command landed" should treat it as success. For every command but CMD_EXECUTE, this outcome is only returned after the full retry budget is spent — see retry_after_unconfirmed_accept_is_safe().

Definition at line 57 of file exchange_engine.h.

FlashDecision

enum class esphome::home_io_control::FlashDecision : uint8_t

strong

Outcome of lr1121_flash_decision().

Enumerator
PROCEED	Safe to erase and write.
ALREADY_INSTALLED	target_fw == installed_fw (both known) — the post-success state.
NEEDS_CONFIRMATION	Not unsafe, but not an unambiguous "yes" either — needs a second press.
REJECT_WRONG_CHIP	device_type or bootloader_version doesn't identify an LR1121.
REJECT_BOOTLOADER_TOO_OLD	target_fw is known and positively incompatible with this bootloader.

Definition at line 235 of file lr1121_firmware_decisions.h.

HeatingFunction

enum class esphome::home_io_control::HeatingFunction : uint8_t

strong

Heating functions, one per user-pressable radiator button in the reference.

Enumerator
POWER_ON	Wake / retrieve paired devices (iohcCozyDevice2W.cpp:105).
SET_TEMPERATURE	Setpoint in degrees Celsius (iohcCozyDevice2W.cpp:125).
SET_MODE	Operating mode (iohcCozyDevice2W.cpp:155).
SET_PRESENCE	Presence / absence (iohcCozyDevice2W.cpp:195).
SET_WINDOW	Open-window / frost-protection (iohcCozyDevice2W.cpp:218).
MIDNIGHT_SYNC	Reads register 0x0130 — the comfort/eco/auto setpoint block (iohcCozyDevice2W.cpp:248; AtlanticThermor/README.md's 0x0130 rows). Named "midnight" in the reference, but the payload is a 0x60 read, not a clock-set: the device's clock register is 0x010F and this component never writes it. Provided for protocol exploration; the 0x21 ACK payload is logged at DEBUG (see IOHomeControlComponent::send_heating_command()).

Definition at line 25 of file proto_heating.h.

HeatingMode

enum class esphome::home_io_control::HeatingMode : uint8_t

strong

Operating modes for HeatingFunction::SET_MODE.

Values from iohcCozyDevice2W.cpp:158-162. The 0x03 "special" mode is commented out at :161 in the reference and is deliberately not exposed here.

Enumerator
AUTO	Automatic mode; device manages the setpoint itself (iohcCozyDevice2W.cpp:158).
MANUAL	Manual mode; follows the last SET_TEMPERATURE setpoint (iohcCozyDevice2W.cpp:159).
PROG	Program mode; device runs its own stored weekly schedule (iohcCozyDevice2W.cpp:160).
OFF	Off / standby; note the value is 0x04, not 0x03 (that is the reference's commented-out "special" mode) (iohcCozyDevice2W.cpp:162).

Definition at line 43 of file proto_heating.h.

ListenOutcome

enum class esphome::home_io_control::ListenOutcome : uint8_t

strong

How one call to ExchangeEngine::listen() ended.

Enumerator
ACCEPTED	The handler returned ReplyDisposition::ACCEPT for some received frame.
ABORTED	The handler returned ReplyDisposition::ABORT for some received frame.
TIMED_OUT	spec.window_ms elapsed with no ACCEPT/ABORT.

Definition at line 119 of file hub_exchange.h.

ListenPolicy

enum class esphome::home_io_control::ListenPolicy : uint8_t

strong

Which channels a listen covers.

A property of what is being waited for, not of the radio: a unicast exchange is a conversation pinned to the channel the request went out on, so its reply always lands there too and there is nothing to hop for. A broadcast has no single recipient, though — every device that answers is continuing its own independent channel-hopping rather than joining a pinned conversation, so the channel it happens to be on when it replies is effectively decoupled from whichever channel carried the request. In practice a broadcast reply essentially never lands back on the requesting channel, so dwelling there wastes part of the listen window. Shared by ExchangeEngine::listen() and, prospectively, any other caller that waits for a radio reply — hence living beside the primitive rather than folded into one loop's local logic.

Enumerator
HOLD_REQUEST_CHANNEL	Never retunes, never slices. Unicast replies.
ROTATE_ALL_CHANNELS	CH1->CH2->CH3->CH1. Broadcast whose reply channel is unknown.
ROTATE_SKIPPING_REQUEST	The two channels that are not the request channel. Roll-call.

Definition at line 105 of file hub_exchange.h.

LR1121RxBandwidth

enum class esphome::home_io_control::LR1121RxBandwidth : uint8_t

strong

Valid LR1121 RX bandwidth options (register values).

Byte-for-byte identical to SX1262RxBandwidth — both chips use the same Semtech GFSK bandwidth grid — and kept as a distinct enum only so each driver's options can diverge if a future chip's table does. See Sx1262AndLr1121BandwidthTablesAgree, which pins the two tables together; if they ever need to differ for a real chip difference, say why here.

Enumerator
BW_39_0_KHZ	39.0 kHz — narrowest; close to SX1276's validated 41.7 kHz default.
BW_46_9_KHZ	46.9 kHz — narrow.
BW_58_6_KHZ	58.6 kHz.
BW_78_2_KHZ	78.2 kHz.
BW_117_3_KHZ	117.3 kHz — default.
BW_156_2_KHZ	156.2 kHz — wider tolerance for LO offset.
BW_187_2_KHZ	187.2 kHz — widest selectable option.

Definition at line 62 of file tuning_config.h.

OneWayAddControllerDecodeError

enum class esphome::home_io_control::OneWayAddControllerDecodeError : uint8_t

strong

Decoding outcome for decode_1w_add_controller().

Enumerator
NONE	Decode succeeded; out is populated.
NOT_ONEWAY	CTRL0_PROTOCOL_1W is not set — not a 1W frame at all.
WRONG_COMMAND	frame.cmd is not CMD_ONEWAY_ADD_CONTROLLER.
BAD_LENGTH	Declared payload is not exactly the expected 20 bytes.
KEY_UNWRAP_FAILED	crypto::crypt_1w_key() itself reported failure.

Definition at line 263 of file proto_codecs.h.

OneWayMacStatus

enum class esphome::home_io_control::OneWayMacStatus : uint8_t

strong

Outcome of checking the out-of-length MAC trailer (IoFrame::has_mac) on a decoded CMD_ONEWAY_ADD_CONTROLLER frame.

Kept distinct from a bare bool because a caller-facing report needs to tell these three situations apart: no MAC was ever present to check (the reference implementation's own _p0x30 struct omits the MAC field entirely, so this is a normal, non-error outcome — not every 0x30 on the wire carries one), a MAC was present and matched, or a MAC was present and did not match (evidence the decrypted key is wrong, or the frame was corrupted/forged).

Enumerator
NOT_PRESENT	frame.has_mac was false; nothing to verify.
VERIFIED	frame.has_mac was true and the MAC verified under the recovered key.
FAILED	frame.has_mac was true and the MAC did NOT verify under the recovered key.

Definition at line 239 of file proto_codecs.h.

PairingOutcome

enum class esphome::home_io_control::PairingOutcome : uint8_t

strong

Final disposition of a pairing attempt, used by the result sensor string.

Enumerator
NONE	No attempt has completed yet (initial state).
PAIRED	All three phases completed successfully.
NO_RESPONSE	No device responded to discovery.
INVALID_RESPONSE	Discovery saw traffic but nothing valid.
KEY_EXCHANGE_FAILED	Discovery succeeded but the key exchange did not complete.
CONFIG_FAILED	Key exchange succeeded but SetConfig1 failed (still counted as paired).

Definition at line 78 of file pairing_telemetry.h.

PairingTelemetryEventKind

enum class esphome::home_io_control::PairingTelemetryEventKind : uint8_t

strong

Kind of a recorded telemetry event.

Enumerator
TX	We transmitted a frame.
RX	We received and accepted a frame for the current wait (including a seeded pre-window sighting — see PairingTelemetryEvent::aux).
RX_REJECT	We received a frame that parsed but was rejected (wrong source, wrong command, etc.).
LBT_DEFER	A listen-before-talk check deferred a transmit because the channel was busy.
PHASE	The pairing state machine advanced to a new phase.

Definition at line 28 of file pairing_telemetry.h.

PendingOperationType

enum class esphome::home_io_control::PendingOperationType : uint8_t

strong

Discriminator for entries in the pending-operation deque.

Enumerator
SET_POSITION	set_device_position call (position 0–100 or special values).
SET_TILT	set_device_tilt call (tilt percentage 0–100).
SET_POSITION_AND_TILT	Combined set_device_position_and_tilt call.
DEVICE_COMMAND	Named device command (STOP, FAVORITE, VENT).
SET_LIGHT_STATE	set_light_state call (binary on/off).
SET_LOCK_STATE	set_lock_state call (locked/unlocked).
SET_SWITCH_STATE	set_switch_state call (binary on/off).
ONEWAY_COMMAND	1W named command sent as a controller identity.
ONEWAY_POSITION	1W numeric position sent as a controller identity.
ONEWAY_ENROLL	1W add-controller (0x30) registering an identity.
ONEWAY_UNENROLL	1W remove-controller (0x39) un-registering an identity.
REQUEST_STATUS	request_device_status call (poll for current position).
REQUEST_NAME	request_device_name call (poll for stored device name).
DISCOVER_AND_PAIR	discover_and_pair call (starts 3-phase pairing flow).

Definition at line 27 of file operation_queue.h.

ReplyDisposition

enum class esphome::home_io_control::ReplyDisposition : uint8_t

strong

What the caller wants done with the frame a listen just received.

Enumerator
ACCEPT	This is the frame the caller was waiting for — stop listening, return ACCEPTED.
IGNORE	Unparsable / not ours / wrong exchange — keep listening.
ABORT	An explicit refusal (e.g. CMD_ERROR_RESP) — stop listening, return ABORTED.

Definition at line 112 of file hub_exchange.h.

ScanAddResult

enum class esphome::home_io_control::ScanAddResult : uint8_t

strong

Outcome of add_scan_responder(), so callers can tell a harmless repeat from real loss.

Enumerator
ADDED	New responder recorded.
DUPLICATE	Already recorded from an earlier reply; nothing changed.
FULL	Dropped: SCAN_MAX_REPLIES distinct responders already recorded.

Definition at line 969 of file management_actions.cpp.

SX1262RxBandwidth

enum class esphome::home_io_control::SX1262RxBandwidth : uint8_t

strong

Valid SX1262 RX bandwidth options (kHz register values).

The numeric values are the register-encoded (double-sideband) bandwidth selectors used by RadioSX1262::set_rx_bandwidth() — a regular (mantissa, exponent) grid, with the bandwidth roughly doubling per group.

Byte-for-byte identical to LR1121RxBandwidth below, since both chips share the same Semtech GFSK bandwidth grid; the Sx1262AndLr1121BandwidthTablesAgree test pins that. If these two tables ever need to diverge for a real chip difference, say why here.

Enumerator
BW_39_0_KHZ	39.0 kHz — narrowest; closest to the SX1276's validated 41.7 kHz.
BW_46_9_KHZ	46.9 kHz — narrow.
BW_58_6_KHZ	58.6 kHz — default; the narrowest value validated on real hardware here.
BW_78_2_KHZ	78.2 kHz — just above the ~77 kHz Carson figure for this waveform.
BW_117_3_KHZ	117.3 kHz — the former default.
BW_156_2_KHZ	156.2 kHz.
BW_187_2_KHZ	187.2 kHz — widest selectable option.

Definition at line 32 of file tuning_config.h.

SX1276RxBandwidth

enum class esphome::home_io_control::SX1276RxBandwidth : uint8_t

strong

Valid SX1276 RX bandwidth options (RegRxBw register bytes).

The numeric values are the SX1276 RegRxBw encodings (RxBwMant in bits[4:3], RxBwExp in bits[2:0]) written verbatim to both REG_RX_BW and REG_AFC_BW. Double-sideband bandwidth = FXOSC / (RxBwMant * 2^(RxBwExp+2)) with FXOSC = 32 MHz. Narrower rejects more out-of-band noise (higher sensitivity); wider tolerates more LO frequency offset.

Enumerator
BW_20_8_KHZ	20.8 kHz — narrowest; maximal noise rejection, least LO-offset tolerance.
BW_41_7_KHZ	41.7 kHz — default (validated against real devices).
BW_62_5_KHZ	62.5 kHz.
BW_83_3_KHZ	83.3 kHz.
BW_125_0_KHZ	125.0 kHz — widest selectable option.

Definition at line 48 of file tuning_config.h.

Function Documentation

acei_level_name()

const char * esphome::home_io_control::acei_level_name

(

uint8_t

level

)

Get a human-readable name for an ACEI priority level (0–7).

Priority levels form a hierarchy: level 0 (human protection) is highest and overrides all others. Level 3 is the default for remote controllers.

Parameters

level

Priority level value (0–7).

Returns

Null-terminated string such as "user_default" or "protection_sensor".

Definition at line 213 of file proto_constants.cpp.

add_scan_responder()

ScanAddResult esphome::home_io_control::add_scan_responder ( ScanResponder * responders, uint8_t & count, uint8_t capacity, const IoFrame & frame, int16_t rssi_dbm )

static

Record a responder unless its address is already present.

Deduplication is by node ID across the whole scan, so a device that answers several of the three attempts — or twice inside one attempt — still yields one entry. The duplicate check runs before the capacity check so that repeat replies from already-recorded devices never look like overflow once the array is full.

Parameters

responders	Accumulated array, appended to in place.
count	In: entries already present. Out: updated count.
capacity	Maximum entries responders can hold.
frame	Reply frame to decode and store.
rssi_dbm	RSSI of that reply.

Returns

Which of the three outcomes occurred.

Definition at line 987 of file management_actions.cpp.

Here is the call graph for this function:

address_class_name()

const char * esphome::home_io_control::address_class_name

(

AddressClass

address_class

)

Get a human-readable name for an address classification.

Parameters

address_class

Classification returned by classify_address().

Returns

Null-terminated string such as "broadcast_all" or "unicast".

Definition at line 220 of file proto_codecs.cpp.

apply_error_response()

bool esphome::home_io_control::apply_error_response ( const IoFrame & response, ManagementActionResult & result )

static

Decode a CMD_ERROR_RESP frame's result code into result.

Populates has_result_code/result_code but deliberately leaves result.message untouched: rename and identify_device report different wording for the same decoded code, so message composition stays with each caller. On an empty error response, sets a stock message itself (there is no code to report) and returns false; callers should treat that the same way as a decoded code, just without result-code-specific wording.

Parameters

response	Frame whose cmd is CMD_ERROR_RESP.
result	Result to populate.

Returns

true if a result code was decoded, false if the response carried no data.

Definition at line 356 of file management_actions.cpp.

att_class_name()

const char * esphome::home_io_control::att_class_name

(

uint8_t

att_class

)

Get a human-readable turnaround time string for an ATT class value.

Parameters

att_class

ATT class (0–3) extracted from the Multi Information Byte.

Returns

Null-terminated string such as "5s", "10s", "20s", or "40s".

Definition at line 148 of file proto_constants.cpp.

bandwidth_from_string()

std::optional< uint8_t > esphome::home_io_control::bandwidth_from_string	(	const BandwidthOption *	table,
		size_t	n,
		const std::string &	value )

Parse a YAML/UI bandwidth string against a table, returning the matching register byte.

Accepts surrounding whitespace and a trailing "kHz" suffix in any case, and accepts both the one-decimal spelling ("39.0") and the integer-truncated spelling ("39") of every table entry.

Returns

The register byte, or std::nullopt when the string matches no entry.

Definition at line 89 of file tuning_config.cpp.

bandwidth_to_khz()

float esphome::home_io_control::bandwidth_to_khz	(	const BandwidthOption *	table,
		size_t	n,
		uint8_t	reg,
		float	fallback )

Look up the kHz value for a register byte in a bandwidth table.

Parameters

table	Bandwidth option table.
n	Number of entries in table.
reg	Register byte to look up.
fallback	kHz value returned when reg is not in the table.

Definition at line 75 of file tuning_config.cpp.

bandwidth_to_string()

std::string esphome::home_io_control::bandwidth_to_string

(

float

khz

)

Format a kHz value as its YAML/UI option string (bare number, one decimal, e.g. "117.3").

Definition at line 83 of file tuning_config.cpp.

bool_to_string()

std::string esphome::home_io_control::bool_to_string ( bool value )

static

Definition at line 328 of file management_actions.cpp.

broadcast_target_type()

DeviceType esphome::home_io_control::broadcast_target_type

(

const uint8_t

addr[NODE_ID_SIZE]

)

Extract the target device type from a typed broadcast address.

Broadcast addresses encode the device type in bits [9:2] of the combined address bytes 1–2. This function extracts that type. Returns UNKNOWN if the address is not a broadcast (first byte != 0x00).

Parameters

addr	Three-byte broadcast address.

Returns

DeviceType encoded in the address, or DeviceType::UNKNOWN for unicast.

Definition at line 236 of file proto_codecs.cpp.

build_device_yaml_snippet()

std::string esphome::home_io_control::build_device_yaml_snippet	(	DeviceType	type,
		uint8_t	subtype,
		const std::string &	device_id,
		bool	metadata_complete,
		bool	inverted,
		bool	low_power )

Build the ready-to-paste YAML block describing a device, for both a fully-decoded device and one whose type/subtype wasn't reported.

With metadata_complete == false, the type/subtype are unknown, so the returned snippet uses a <cover|light|switch|lock> platform placeholder and a commented-out io_device_type explanation; type, subtype, and inverted are ignored in this case.

With metadata_complete == true, the snippet names the concrete ESPHome platform for type and fills in io_subtype and (for an inverted cover) invert_position: true. If type has no known ESPHome platform, an empty string is returned instead — the caller decides what to say when there's no snippet to show.

low_power: true is emitted in both shapes when low_power is set (the device self-reported POWER_SAVE_LOW_POWER in its discovery Multi Information Byte); it is omitted entirely otherwise, since its absence is a valid, correct config.

The emitted keys must track the device-bound platform schemas (platform_schema_extension() in platform_common.py, plus each of cover.py/light.py/switch.py/lock.py's own extra keys) by hand. make yaml-emitter-sync (scripts/check-yaml-emitters.py) catches drift between the two statically.

Parameters

type	Decoded device type.
subtype	Decoded device subtype; only used when metadata_complete is true.
device_id	Hex device ID string (e.g. "38B4A1").
metadata_complete	Whether the discovery response included type/subtype metadata.
inverted	Whether the device's open/close positions are swapped; only used when metadata_complete is true and type is a cover.
low_power	Whether the device self-reported a low-power / duty-cycled class; emits low_power: true when set, in both snippet shapes.

Returns

Multi-line YAML snippet, or an empty string when metadata_complete is true but type maps to no ESPHome platform.

Definition at line 431 of file proto_device_model.cpp.

Here is the call graph for this function:

bytes_to_hex()

void esphome::home_io_control::bytes_to_hex ( const uint8_t * data, uint8_t len, char * out, size_t out_size )

inline

Definition at line 22 of file log_frame.h.

classify_address()

AddressClass esphome::home_io_control::classify_address

(

const uint8_t

addr[NODE_ID_SIZE]

)

Classify an IO-Homecontrol 3-byte address.

Determines whether an address is unicast, a typed broadcast, or a discovery-related broadcast based on protocol addressing rules.

Parameters

addr	Three-byte node address to classify.

Returns

Classification indicating the address type.

Definition at line 196 of file proto_codecs.cpp.

command_carries_key_material()

bool esphome::home_io_control::command_carries_key_material ( uint8_t cmd )

inline

Whether a frame command's payload carries key material that must never be logged or reported verbatim.

CMD_KEY_TRANSFER (0x32) carries the system key encrypted with the pairing transfer key — still key material, so callers rendering frame bytes must mask this payload rather than print it.

CMD_CHALLENGE_REQ (0x3C) and CMD_CHALLENGE_RESP (0x3D) are masked for the same reason even though neither carries the key itself: create_hmac() builds the 0x3D payload by AES-128-ECB encrypting an IV built from the 0x3C challenge and the challenged frame's own (plaintext) transcript under the system key, then truncating to 6 bytes (proto_crypto.cpp). Logging both frames publishes a known-plaintext/known-ciphertext pair for that block cipher under the system key, so they get the same treatment as literal key material.

CMD_ONEWAY_ADD_CONTROLLER (0x30) is the 1W equivalent of CMD_KEY_TRANSFER. Its payload is not literally the key — it is the key wrapped with the public TRANSFER_KEY — but the unwrap needs nothing secret: the IV derives only from the sender's node address, which is plaintext in the same frame's header. So publishing those bytes is equivalent to publishing the key, and they are masked for the same reason 0x32 is. The one deliberate exception is the adoption report in oneway_key_adoption.cpp, which formats the decoded key directly rather than going through any frame-rendering path.

Parameters

cmd	Frame command byte.

Returns

true if the payload of a frame with this command must be masked.

Definition at line 46 of file redaction.h.

command_name()

const char * esphome::home_io_control::command_name

(

uint8_t

cmd

)

Get a human-readable name for any IO-Homecontrol command ID.

Returns a short uppercase identifier suitable for log lines (e.g., "EXECUTE", "DISCOVER_REQ", "CHALLENGE_RESP"). Unknown commands return "UNKNOWN_CMD".

Parameters

cmd	Command byte from the frame header.

Returns

Null-terminated string.

Definition at line 10 of file proto_constants.cpp.

command_result_description()

const char * esphome::home_io_control::command_result_description

(

uint8_t

result

)

Return a human-readable explanation for a CMD_ERROR_RESP result code.

Parameters

result

Result byte from CMD_ERROR_RESP data[0].

Returns

Short description suitable for warn-level logs.

Definition at line 347 of file proto_constants.cpp.

command_result_name()

const char * esphome::home_io_control::command_result_name

(

uint8_t

result

)

Return a stable symbolic name for a CMD_ERROR_RESP result code.

Parameters

result

Result byte from CMD_ERROR_RESP data[0].

Returns

Uppercase symbolic name, or "UNKNOWN_RESULT_CODE" when unmapped.

Definition at line 236 of file proto_constants.cpp.

contains_key_material()

bool esphome::home_io_control::contains_key_material ( const uint8_t * buf, size_t len, const uint8_t * system_key )

inline

Whether a buffer contains the system key as a contiguous run of bytes.

A last-line-of-defense scan for accidental key leaks in ad hoc debug or report text, independent of which command produced the buffer.

Parameters

buf	Buffer to scan.
len	Length of buf in bytes.
system_key	Pointer to the AES_KEY_SIZE-byte system key.

Returns

true if system_key appears anywhere in buf.

Definition at line 59 of file redaction.h.

cover_command_name()

const char * esphome::home_io_control::cover_command_name

(

CoverCommand

cmd

)

Get a human-readable name for a CoverCommand.

Parameters

cmd	The cover command to name.

Returns

Null-terminated string such as "STOP", "FAVORITE", or "VENT".

Definition at line 46 of file proto_device_model.cpp.

crc_ccitt()

uint16_t esphome::home_io_control::crc_ccitt	(	const uint8_t *	data,
		uint8_t	len )

CRC-CCITT used by the IO-Homecontrol protocol for frame validation.

Compute CRC‑CCITT (poly 0x1021, init 0x0000) over a buffer.

Polynomial: 0x1021 (reversed 0x8408), initial value: 0x0000. Radio chips with native IO-Homecontrol framing compute this in hardware; drivers for other chips call this helper instead.

Used by radio drivers without hardware IO-Homecontrol CRC support and by frame validation in tests.

Parameters

data	Pointer to data bytes.
len	Number of bytes.

Returns

16‑bit CRC value.

Definition at line 60 of file proto_frame.cpp.

create_1w_add_controller()

bool esphome::home_io_control::create_1w_add_controller	(	IoFrame &	f,
		const uint8_t	src[NODE_ID_SIZE],
		DeviceType	target_type,
		uint8_t	manufacturer,
		uint16_t	sequence,
		const uint8_t	controller_key[AES_KEY_SIZE],
		bool	with_mac )

Build a 1W add-controller frame (CMD 0x30).

Build a 1W add-controller frame (CMD 0x30) that registers this identity as a controller on every device of target_type currently in association mode — a physical 2 s PROG hold on the receiver, which only the device's owner can trigger (see ADR 0026).

See proto_commands.h for the full contract, including why the MAC is an optional, out-of-length trailer here and not inside the declared payload, and why with_mac exists at all (real hardware omits it; the published vector doesn't).

The payload wraps controller_key for transmission rather than sending it in the clear: enc_key = crypto::crypt_1w_key(src, controller_key), the same self-inverse primitive decode_1w_add_controller() uses to unwrap an overheard 0x30 (crypt_1w_key() is its own inverse, so this call and that one are literally the same function). The wrap key is the public TRANSFER_KEY (proto_constants.h) and the wrap IV derives only from src — see crypt_1w_key()'s doxygen for why that is not a weakness: the receiver decrypts enc_key first, then checks this frame's MAC under the key it just recovered, which is what makes the MAC meaningful (it proves the sender holds the key it just sent), not the wrap's secrecy.

Declared payload (20 bytes): enc_key[16] + manufacturer[1] + data[1]=0x01 + sequence[2]. When with_mac is true, the MAC is an out-of-length trailer, not part of the declared payload — CTRL0's 5-bit length field cannot express 29 declared bytes plus a 6-byte MAC together (see IoFrame::has_mac, frame_carries_mac_trailer() in proto_frame.h), so this builder sets f.has_mac = true and fills f.mac[] directly; serialize() appends it after the declared length and folds it into the length it returns, so a caller's CRC (computed over that return value) covers it automatically. When present, this is the opposite placement from create_1w_remove_controller() below, whose MAC sits inside the declared payload — copying one builder's shape to make the other is the most likely bug a future edit introduces here.

Warning

Real hardware and the published documentation vector disagree on whether the MAC trailer exists at all — this is why with_mac is a parameter, not a fixed choice. The published linklayer.md vector (with_mac=true, 35 bytes) is what with_mac defaults to, for compatibility with that vector's own pinning tests. Most real hardware captures instead show 29 bytes with no trailer at all — see tests/corpus/captures/enrollment/somfy_smoove_enrollment_add_and_remove_controller_sx1276.yaml — matching the reference _p0x30 struct (iohcPacket.h, no hmac field). The enroll button calls this with with_mac=false to match that shape, but this is a preference rather than a hardware requirement: a real Somfy Izymo dimmer has separately been shown to accept the with_mac=true form as well, enrolling successfully and remaining controllable afterward — both shapes are safe to send.

Reference divergences, deliberately not followed: the iown-homecontrol project's create_key_transfer_1w derives the key-wrap IV from the destination node, which contradicts the published frame this builder is pinned against (a broadcast destination carries no identity, so src is the only value that reproduces it); and its comment claims "key transfer carries no MAC", which the same published frame also contradicts (its MAC is genuine and verifies) — that claim is a coincidental match for what real hardware turned out to do, not evidence the comment's reasoning was right.

Parameters

f	IoFrame to populate.
src	Our 3-byte controller node address (the 1W controller identity's node_id) — also the key-wrap IV's only input, so this must be the identity actually being registered.
target_type	Device class to address; encoded via encode_broadcast_address(). Only devices of this class currently in association mode react.
manufacturer	Manufacturer ID byte to advertise (man_id); echoed back verbatim by anything that later decodes this frame with decode_1w_add_controller().
sequence	2-byte rolling sequence for this transmission (big-endian on wire); the caller's identity/sequence store owns incrementing and persisting this, not this builder.
controller_key	16-byte key this identity registers itself with — normally the hub's own system_key, wrapped here for transmission, never sent in the clear.
with_mac	True to append the out-of-length MAC trailer (the published vector's shape, and this parameter's default for backward compatibility); false to omit it entirely (the shape most real hardware captures this project holds actually use, and what the enroll button passes). Real hardware has been shown to accept both — see the @warning above.

Returns

true on success; false if crypto::crypt_1w_key() fails, or (when with_mac is true) crypto::create_1w_hmac() fails — no partially-populated frame is left behind on failure.

Definition at line 384 of file proto_commands.cpp.

Here is the call graph for this function:

create_1w_execute_command()

bool esphome::home_io_control::create_1w_execute_command	(	IoFrame &	f,
		const uint8_t	src[NODE_ID_SIZE],
		DeviceType	target_type,
		CoverCommand	cmd,
		uint16_t	sequence,
		const uint8_t	controller_key[AES_KEY_SIZE],
		uint8_t	acei,
		bool	broadcast_all )

Build a 1W named-command execute frame (CMD 0x00) targeting a device class.

See proto_commands.h for the full contract, including why 1W has no FORCE_OPEN: the only known wire encoding for the label (POS_FORCE_OPEN, main=0x64) was hardware-tested as an ordinary move-to-50% command, not a lock bypass — see the POS_FORCE_OPEN doc comment in proto_constants.h. Passing CoverCommand::FORCE_OPEN here falls through to default and returns false, matching 2W's create_execute_command().

Covers three of CoverCommand's values — STOP, FAVORITE, VENT. FORCE_OPEN is not handled here: the only wire code this project has for that label, POS_FORCE_OPEN (main=0x64), was hardware-tested as an outbound CMD_EXECUTE command and found to move a real device to 50% open, not bypass anything (see POS_FORCE_OPEN in proto_constants.h). There is no known 1W force-open encoding, so passing CoverCommand::FORCE_OPEN here falls to default and returns false, the same way create_execute_command()'s 2W dispatch rejects it.

• STOP: main=POS_STOP (0xD2), modifier=0x00
• FAVORITE: main=POS_FAVORITE (0xD8), modifier=0x00
• VENT: main=POS_FAVORITE (0xD8), modifier=POS_VENT_MODIFIER (0x03)

Warning

These three do not rest on the same evidence, even though they read as a uniform list. STOP is the only one a real frame pins: the published IV vector (tests/corpus/captures/oneway/reference_1w_oneway_execute_iv_vector.yaml) is a documented worked example carrying main=0xD2. VENT is not captured anywhere in this project, but it does match the reference implementation's own 1W remote byte-for-byte — its RemoteButton::Vent emits exactly main=0xD8/mod=0x03. FAVORITE has neither kind of support: that same reference remote has no distinct favorite/My button at all (its RemoteButton set is Open/Close/Stop/Vent/ForceOpen/Position/Absolute/Pair/Add/Remove/ Mode1-4 — no Favorite), so main=0xD8/mod=0x00 here is extrapolated purely by analogy with the 2W builder's FAVORITE encoding, with no source behind it at all. Worse, the one real capture this project has of an actual My/favorite button press — tests/corpus/captures/oneway/somfy_smoove_oneway_favorite_sx1276.yaml, pinned by OneWayCommands.FavoriteButtonCaptureIsWritePrivateNotExecute in tests/oneway_commands_test.cpp — contradicts it directly: that remote's My button is CMD_WRITE_PRIVATE (0x20) with a 16-byte payload, not CMD_EXECUTE with main=0xD8.

A real enrolled device does act on main=0xD8/mod=0x00, though: it changed the brightness of a Somfy Izymo dimmer, so the byte is accepted, not ignored. What position it targets — a stored "My" position vs. some fixed value — is unconfirmed; a 2W status-poll readback would settle it. Treat FAVORITE as "does something, target unverified", not "plausibly wrong".

FORCE_OPEN is deliberately absent rather than merely untested. The reference remote's RemoteButton::ForceOpen emits main=0x64/mod=0x00 — the same bytes this project labels POS_FORCE_OPEN — so it would "match the reference implementation byte-for-byte" the same way VENT does above. But matching the reference is not evidence it works: this project hardware-tested that exact main byte as an outbound CMD_EXECUTE and confirmed it moves a real device to 50% open (see POS_FORCE_OPEN in proto_constants.h), not past any lock. There is no known 1W encoding for a real force-open, so it is unimplemented rather than shipped on a mislabeled byte.

The MAC span is the 7 bytes cmd, origin, acei, main0, main1, fp1, fp2 — the command byte through fp2, stopping before the sequence, which is not frame data and never enters the MAC. Pinned by the published IV vector at tests/corpus/captures/oneway/reference_1w_oneway_execute_iv_vector.yaml and by the reference implementation's own 1W-remote span (toAdd = 6 + 1). This span is command-specific and does not generalise: CMD 0x30's span is cmd + enc_key only — see crypto::create_1w_hmac()'s @warning.

Parameters

f	IoFrame to populate.
src	Our 3-byte controller node address (the 1W controller identity's node_id).
target_type	Device class to address; encoded via encode_broadcast_address().
cmd	Named command to execute (STOP, FAVORITE, or VENT). CoverCommand::FORCE_OPEN returns false — see the

Warning

above.

Parameters

sequence	2-byte rolling sequence for this transmission (big-endian on wire); the caller's identity/sequence store owns incrementing and persisting this, not this builder — see the section note above.
controller_key	16-byte key held by the transmitting controller identity: the hub's own system_key for its own network, or a foreign key adopted via CMD 0x30 (Phase 3A "key adoption") when transmitting as an adopted identity.
acei	ACEI byte for payload[1] — see create_1w_execute_position().
broadcast_all	Address 00 00 3F instead of the typed class — see create_1w_execute_position().

Returns

true on success; false if cmd is CoverCommand::FORCE_OPEN (no 1W encoding exists) or if crypto::create_1w_hmac() fails.

Definition at line 358 of file proto_commands.cpp.

create_1w_execute_position()

bool esphome::home_io_control::create_1w_execute_position	(	IoFrame &	f,
		const uint8_t	src[NODE_ID_SIZE],
		DeviceType	target_type,
		uint8_t	position,
		uint16_t	sequence,
		const uint8_t	controller_key[AES_KEY_SIZE],
		uint8_t	acei,
		bool	broadcast_all )

Build a 1W position execute frame (CMD 0x00) targeting a device class.

See proto_commands.h for the full contract.

Encodes a 0–100 position into the 2-byte main field (wire value is 2 * position, matching the 2W numeric encoding) inside 1W's 6-byte "special" payload form — 1W uses this short form even for numeric positions, not the 8-byte layout create_execute_position() (2W) uses. The MAC span is command-specific (see create_1w_execute_command()'s doxygen); there is no default, so this builder assembles it itself via the shared internal helper.

Note

Position 50 encodes as 2 * 50 = 0x64 on the wire, the same byte decode_1w_main_intent() labels POS_FORCE_OPEN when reading overheard traffic. That label is a decode-side diagnostic choice only (see POS_FORCE_OPEN in proto_constants.h) — it does not change what this builder sends or what a device does with it. Position 50 is an ordinary position command.

Parameters

f	IoFrame to populate.
src	Our 3-byte controller node address (the 1W controller identity's node_id).
target_type	Device class to address; encoded via encode_broadcast_address().
position	Desired position 0–100 (0=fully open, 100=fully closed).
sequence	2-byte rolling sequence for this transmission (big-endian on wire); the caller's identity/sequence store owns incrementing and persisting this, not this builder — see the section note above.
controller_key	16-byte key held by the transmitting controller identity: the hub's own system_key for its own network, or a foreign key adopted via CMD 0x30 (Phase 3A "key adoption") when transmitting as an adopted identity.
acei	ACEI byte to place at payload[1] — ONEWAY_EXECUTE_ACEI (Somfy-shaped) by default, ONEWAY_EXECUTE_ACEI_VELUX for a VELUX identity. Resolved per identity by oneway_controller.h's effective_execute_acei(); this builder just writes it.
broadcast_all	When true, address the all-devices broadcast 00 00 3F instead of the typed target_type class — what a handheld cover remote does (execute_broadcast: all).

Returns

true on success; false if position > 100 or if crypto::create_1w_hmac() fails — no partially-populated frame is left behind on failure.

Definition at line 343 of file proto_commands.cpp.

create_1w_remove_controller()

bool esphome::home_io_control::create_1w_remove_controller	(	IoFrame &	f,
		const uint8_t	src[NODE_ID_SIZE],
		DeviceType	target_type,
		uint16_t	sequence,
		const uint8_t	controller_key[AES_KEY_SIZE] )

Build a 1W remove-controller frame (CMD 0x39).

Build a 1W remove-controller frame (CMD 0x39) that un-registers this identity from every device of target_type currently in association mode — the un-enroll counterpart to create_1w_add_controller(), and (per the documented 0x39 → 0x30 flow, linklayer.md:396) also the prelude OneWayTransmitter::send_enrollment() fires immediately before it.

See proto_commands.h for the full contract, including the

Warning

that no vector pins this command's MAC span.

Declared payload (9 bytes), shape matching the reference _p0x2e struct: data[1]=0x00 + sequence[2] + mac[6]. The MAC sits inside the declared payload here — the opposite placement from create_1w_add_controller() above, whose MAC is an out-of-length trailer because its longer payload has no room left in CTRL0's 5-bit length field. f.has_mac stays false.

The MAC span is cmd + data (2 bytes) — the same "everything before the sequence" shape CMD 0x00's span follows, though spans are command-specific and do not generalise on their own (see create_1w_hmac()'s @warning; CMD 0x30's span is cmd + enc_key, a different rule). This one is verified against real captures, not merely plausible: every 0x39 frame in tests/corpus/captures/enrollment/somfy_smoove_enrollment_add_and_remove_controller_sx1276.yaml verifies under this exact span, and scripts/corpus/validate.py re-checks that on every corpus validation run — a regression here would fail make corpus-validate, not just look wrong.

Parameters

f	IoFrame to populate.
src	Our 3-byte controller node address (the 1W controller identity's node_id).
target_type	Device class to address; encoded via encode_broadcast_address().
sequence	2-byte rolling sequence for this transmission (big-endian on wire); the caller's identity/sequence store owns incrementing and persisting this, not this builder.
controller_key	16-byte key held by the identity being removed — the same key create_1w_execute_command()/create_1w_add_controller() would use for this identity.

Returns

true on success; false if crypto::create_1w_hmac() fails — no partially-populated frame is left behind on failure.

Definition at line 430 of file proto_commands.cpp.

Here is the call graph for this function:

create_address_resp_device_role()

bool esphome::home_io_control::create_address_resp_device_role	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst )

Build an address response (0x37) — device side, used only by the key-extraction responder.

Build an address response (0x37) — device side, answering a hub's CMD_ADDRESS_REQ (0x36).

See proto_commands.h for the full contract, including why the payload (our own node ID, not a separately-tracked backbone identity) is a known simplification rather than a confirmed match to real-device behavior.

TODO(hardware-verify): ctrl1 is 0x00 here (no CTRL1_PRIORITY), matching every other device-role builder in this file, but the one real capture of this command (tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml line 87) shows CTRL1_PRIORITY set on the KLR200's 0x37. In that same capture the device also mirrors CTRL1_PRIORITY from whatever the hub's preceding request set, and its 0x36 request is the one request in the whole exchange that sets PRIORITY — but every other device-role builder here also emits ctrl1=0 against frames that same capture shows with reserved/other bits set, and those builders are hardware-confirmed working (issue #45's own captures), so this one bit's necessity is unproven rather than known missing. Not mirroring the request's PRIORITY bit until a second real capture settles it either way.

Payload is our own advertised node ID — the only identity this emulated device has to offer — the same value create_discover_resp() reports at DISCOVERY_RESP_BACKBONE_OFFSET. CorpusDeviceRoleBuilders.AddressRespPayloadMatchesOwnDiscoverRespBackboneAddress (tests/corpus_device_role_builder_test.cpp) pins that these two builders agree with each other, not that this matches a real device's own backbone value: the one real capture of this exchange (tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml) shows a genuine device whose 0x37 payload — a persistent identity the io-homecontrol wire format tracks separately from a device's node/session address — does NOT equal that device's own node ID. Our emulated device only ever generates one identity per arm cycle, so it structurally cannot reproduce a real device's separate backbone value; whether any real hub requires the two to differ, or even inspects this field at all rather than treating it as informational, is unconfirmed. See docs/home_io_control.md's Key Extraction "Known limitations" for the field-facing version of this note. Also unverified: the full CTRL1 framing. This builder's ctrl1 is 0x00 (see init_frame() call in the .cpp), but the KLR200 capture's 0x37 carries CTRL1_PRIORITY set. See the TODO(hardware-verify) on the .cpp definition for why that bit is not mirrored here. No controller-role counterpart exists to share with: this codebase has never sent 0x36, so there is no analogous controller-role code that receives a 0x37 to keep in sync with.

Parameters

f	IoFrame to populate.
own	Our advertised (throwaway) node ID — used as both src and the payload.
dst	Destination node ID (the hub that sent the address request, from its 0x36's src).

Returns

true on success.

Definition at line 829 of file proto_commands.cpp.

Here is the call graph for this function:

create_challenge_req() [1/2]

bool esphome::home_io_control::create_challenge_req	(	IoFrame &	f,
		const uint8_t *	dst,
		const uint8_t *	src )

Build a challenge request (0x3C) containing 6 random bytes.

Used when WE need to authenticate an incoming request from a device.

Used when we need to authenticate an incoming request from a device.

Parameters

f	IoFrame to populate.
dst	Target device node ID (device we're challenging).
src	Controller node ID.

Returns

true on success.

Definition at line 773 of file proto_commands.cpp.

Here is the call graph for this function:

create_challenge_req() [2/2]

bool esphome::home_io_control::create_challenge_req	(	IoFrame &	f,
		const uint8_t *	dst,
		const uint8_t *	src,
		const uint8_t	challenge[HMAC_SIZE] )

Build a challenge request (0x3C) using a caller-supplied challenge.

Build a challenge request (0x3C) using a caller-supplied challenge instead of generating a fresh one internally.

See proto_commands.h.

Framed exactly like the device-role builder below (0E 00, no START, no LOW_POWER) — matches every 0x3C observed on air across multiple actuators and vendors. Kept as a separate entry point from create_challenge_req_device_role() because the call sites and rationale differ (inbound authentication vs the key-extraction responder). If devices ever stop answering our challenges, START/LOW_POWER framing is the first thing to try restoring here.

The no-challenge overload above generates its own random bytes and does not expose them, which is fine for the normal inbound-auth path (the challenge is only ever needed once, to build this same frame). A caller that needs the exact bytes again later — the key-extraction responder decrypting the corresponding CMD_KEY_TRANSFER (0x32) — generates the challenge itself and passes it in here, keeping the transmitted 0x3C and the later decrypt on one source of truth. Note that responder uses create_challenge_req_device_role() below, not this overload.

Parameters

f	IoFrame to populate.
dst	Target device node ID (device we're challenging).
src	Our own node ID.
challenge	Caller-supplied 6-byte challenge (e.g. from crypto::generate_challenge()).

Returns

true on success.

Definition at line 767 of file proto_commands.cpp.

Here is the call graph for this function:

create_challenge_req_device_role()

bool esphome::home_io_control::create_challenge_req_device_role	(	IoFrame &	f,
		const uint8_t *	dst,
		const uint8_t *	src,
		const uint8_t	challenge[HMAC_SIZE] )

Build a device-role challenge request (0x3C) — device side, used only by the key-extraction responder.

Build a challenge request (0x3C) in the device direction — used only by the key-extraction responder to challenge a foreign hub that sent us CMD_KEY_INIT (0x31).

See proto_commands.h for why the framing bits differ from the controller-role builders above.

Same command and payload as the controller-role builders above, but framed the way a real device frames it: START clear and LOW_POWER clear. Both controller-role overloads set both bits, which is correct for their direction — LOW_POWER describes the target of a controller-originated frame (a device that may be battery/solar powered, see this header's convention note), and the controller's 0x3C opens its own inbound-auth exchange. Neither holds for a device answering a hub's key-init: real devices' pairing 0x3C frames in tests/corpus/captures/pairing/somfy_izymo_dimmer_pairing_full_sx1276.yaml (0E 00 …) and tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml carry neither bit, because the frame is a continuation of the hub's already-open exchange and is addressed to a mains-powered hub — and this exact builder, exercised against a real hub, produces the identical 0E 00 shape in tests/corpus/captures/pairing/velux_kig300_pairing_key_extraction_success.yaml.

Parameters

f	IoFrame to populate.
dst	The foreign hub's node ID (from the inbound 0x31's src).
src	Our advertised (throwaway) node ID.
challenge	Caller-supplied 6-byte challenge, retained for the later 0x32 decrypt.

Returns

true on success.

Definition at line 782 of file proto_commands.cpp.

Here is the call graph for this function:

create_challenge_req_framed()

bool esphome::home_io_control::create_challenge_req_framed ( IoFrame & f, const uint8_t * dst, const uint8_t * src, const uint8_t challenge[HMAC_SIZE], bool start, bool low_power )

static

Build a challenge request (0x3C) with caller-chosen framing bits.

Shared by the controller-role and device-role builders below, which differ only in those bits.

Definition at line 752 of file proto_commands.cpp.

Here is the call graph for this function:

create_challenge_resp()

bool esphome::home_io_control::create_challenge_resp	(	IoFrame &	f,
		const uint8_t *	dst,
		const uint8_t *	src,
		const uint8_t	challenge[HMAC_SIZE],
		const IoFrame &	origin,
		const uint8_t *	key )

Build a challenge response (0x3D) proving we know the system key.

The HMAC is computed over [original_command_id + original_data] using the challenge.

HMAC is computed over [original_command_id + original_data] using the challenge.

Parameters

f	IoFrame to populate.
dst	Target device node ID.
src	Controller node ID.
challenge	6‑byte challenge from the device.
origin	Original request frame that triggered the challenge.
key	System key (16 bytes).

Note

The HMAC derivation uses the challenge as IV salt; see create_hmac() in proto_crypto.h for the exact construction. This frame authenticates the controller to the device for the current exchange.

Returns

true on success.

Definition at line 809 of file proto_commands.cpp.

Here is the call graph for this function:

create_challenge_resp_device_role()

bool esphome::home_io_control::create_challenge_resp_device_role	(	IoFrame &	f,
		const uint8_t *	dst,
		const uint8_t *	src,
		const uint8_t	challenge[HMAC_SIZE],
		const IoFrame &	origin,
		const uint8_t *	key )

Build a device-role challenge response (0x3D) — device side, used only by the key-extraction responder answering a hub-issued 0x3C challenging our own 0x37.

Build a challenge response (0x3D) in the device direction — used only by the key-extraction responder to answer a hub-issued CMD_CHALLENGE_REQ (0x3C) challenging our own CMD_ADDRESS_RESP (0x37).

See proto_commands.h for why the framing bits differ from the controller-role builder above.

Same transcript rule as create_challenge_resp() above (the challenged party HMACs its own preceding frame's cmd+data), but END is set: this 0x3D closes the address-verification round the hub opened with 0x36 (tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml's 8E 08 …, END set). LOW_POWER is clear because CTRL1_LOW_POWER describes a controller-originated frame's target, not the sender — irrelevant here, since this is a device-role frame sent to a mains-powered hub. Unrelated to create_discover_resp()'s own Multi Information Byte, which as of KEY_EXTRACTION_DISCOVER_RESP_FLAGS (proto_commands.cpp) deliberately advertises POWER_SAVE_LOW_POWER for this responder's own (different) power-save self-description — the two bits answer different questions and are not expected to match. Neither bit is a blanket "device role" convention — real devices also send mid-exchange 0x3D frames with END clear and LOW_POWER set (somfy_oximo40_statuspoll_sx1262.yaml) — so this framing is specific to the terminal shape this feature needs, not a general device-role rule.

Parameters

f	IoFrame to populate.
dst	The hub's node ID (from the inbound 0x3C's src).
src	Our advertised (throwaway) node ID.
challenge	6-byte challenge from the hub's 0x3C.
origin	Our own preceding CMD_ADDRESS_RESP (0x37) frame — its cmd+data is the transcript.
key	System key (16 bytes).

Returns

true on success.

Definition at line 839 of file proto_commands.cpp.

Here is the call graph for this function:

create_challenge_resp_framed()

bool esphome::home_io_control::create_challenge_resp_framed ( IoFrame & f, const uint8_t * dst, const uint8_t * src, const uint8_t challenge[HMAC_SIZE], const IoFrame & origin, const uint8_t * key, bool end, bool low_power )

static

Build a challenge response (0x3D) with caller-chosen framing bits.

Shared by the controller-role and device-role builders below, which differ only in those bits — see create_challenge_req_framed() above for the identical pattern on the request side.

Definition at line 790 of file proto_commands.cpp.

Here is the call graph for this function:

create_device_terminal_ack()

bool esphome::home_io_control::create_device_terminal_ack ( IoFrame & f, const uint8_t * own, const uint8_t * dst, uint8_t cmd )

static

Build a bare device→hub terminal acknowledgement: no payload, END set, START and LOW_POWER clear.

Shared by create_key_confirm() and create_discover_confirm_ack(), which are the same frame shape and differ only in command byte — real captures of both (tests/corpus/captures/pairing/somfy_izymo_dimmer_pairing_full_sx1276.yaml's 0x33 88 00 …, velux_kux100_pairing_full.yaml's 0x2D 88 08 …, and this project's own key-extraction responder against a real hub in tests/corpus/captures/pairing/velux_kig300_pairing_key_extraction_success.yaml, both 0x2D and 0x33 as 88 00 …) show a device closing its half of a two-frame handshake this way. LOW_POWER stays clear because that bit describes the target of a controller-originated frame (see the header's convention note); a device does not flag a frame it sends to the hub as low-power.

Definition at line 698 of file proto_commands.cpp.

Here is the call graph for this function:

create_discover()

bool esphome::home_io_control::create_discover	(	IoFrame &	f,
		const uint8_t *	own )

Build a discovery broadcast (0x28).

Sent to the broadcast address 0x00003B. Only devices in pairing mode (PROG button pressed) will respond.

Sent to the broadcast address; only devices in pairing mode (PROG button pressed) will respond.

Parameters

f	IoFrame to populate.
own	Controller node ID.

Note

Destination is BROADCAST_DISCOVER (0x00003B). The device responds with CMD_DISCOVER_RESP (0x29) containing its node ID and type/subtype. The controller then switches to point‑to‑point communication for phases 2 and 3.

Returns

true on success.

Definition at line 609 of file proto_commands.cpp.

Here is the call graph for this function:

create_discover_confirm_ack()

bool esphome::home_io_control::create_discover_confirm_ack	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst )

Build a discovery-confirm acknowledgement (0x2D) — device side, used only by the key-extraction responder.

Build a discovery-confirm acknowledgement (0x2D) — the device's answer to a hub's CMD_DISCOVER_CONFIRM (0x2C), which a hub sends directly to a freshly-discovered device before it will proceed to the key exchange.

See proto_commands.h for the full contract.

Device-side only, like create_discover_resp()/create_key_confirm() above; this project's own controller role never sends 0x2C, so there is no counterpart builder for the other direction. No payload and END set, matching real devices' 0x2D in tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml; for a second independent hub, tests/corpus/captures/pairing/somfy_connectivity_kit_pairing_key_extraction_stall.yaml, where an already-paired device answers the same hub the key-extraction responder was talking to; and for this exact builder exercised against a real hub, tests/corpus/captures/pairing/velux_kig300_pairing_key_extraction_success.yaml.

Parameters

f	IoFrame to populate.
own	Our advertised (throwaway) node ID.
dst	Destination node ID (the hub that sent the discovery confirm).

Returns

true on success.

Definition at line 713 of file proto_commands.cpp.

Here is the call graph for this function:

create_discover_resp()

bool esphome::home_io_control::create_discover_resp	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		DeviceType	type,
		uint8_t	subtype,
		uint8_t	manufacturer_id )

Build a discovery response (0x29) — device side, used only by the key-extraction responder.

Build a discovery response (0x29) — the device side of discovery, used by the key-extraction responder (see pairing_responder.h) to emulate an unpaired device.

See proto_commands.h for the full contract and the real-capture cross-check.

Almost every builder in this file speaks the controller side of the protocol; this one, create_key_confirm(), create_discover_confirm_ack(), and create_challenge_req_device_role() below speak the device side, needed only for that one reverse-role feature. Device-side frames never set CTRL1_LOW_POWER: that bit describes the target of a controller-originated frame, and a device's replies are addressed to a mains-powered hub. Payload layout matches the full 9-byte discovery response format documented at DISCOVERY_RESP_BACKBONE_OFFSET/_MANUFACTURER_OFFSET/_FLAGS_OFFSET/_TIMESTAMP_OFFSET (proto_constants.h), cross-checked against a real Somfy actuator's captured 0x29 (tests/corpus/captures/discovery/somfy_awning_discovery_lab_response.yaml): backbone address equals the device's own node ID, start+end set, low_power clear.

Parameters

f	IoFrame to populate.
own	Our advertised (throwaway) node ID — used as both src and the backbone address.
dst	Destination node ID (the discovering hub's real node ID, from its 0x28's src).
type	Device type to advertise.
subtype	Device subtype to advertise.
manufacturer_id	Manufacturer ID to advertise (see MANUFACTURER_* in proto_constants.h).

Note

The flags byte (turnaround class, power-save) and timestamp are best-effort placeholder values — ATT_CLASS_40S/POWER_SAVE_LOW_POWER and a non-zero timestamp, matching a real captured device rather than the honest-but-misleading ATT_CLASS_5S/POWER_SAVE_ALWAYS_ALIVE (0x00) — see KEY_EXTRACTION_DISCOVER_RESP_FLAGS/_TIMESTAMP in proto_commands.cpp for the full reasoning. Still unverified against a real hub.

Returns

true on success.

Definition at line 667 of file proto_commands.cpp.

Here is the call graph for this function:

create_discovery_request()

bool esphome::home_io_control::create_discovery_request	(	IoFrame &	f,
		const uint8_t *	own,
		uint8_t	command,
		const uint8_t *	dst,
		bool	low_power,
		bool	payload_enabled,
		uint8_t	payload,
		const uint8_t *	system_key )

Build a configurable discovery request command (0x28, 0x2A, or 0x2E).

Build a discovery request with configurable command, destination, and payload.

For 0x2A (Discover SPE), the payload is a 6-byte random nonce followed by a 6-byte HMAC over the command byte alone, using that nonce as the challenge and the supplied system key — one frame carrying a whole challenge-response, which is what lets a broadcast be authenticated. This requires a valid system key; it will not work for a motor that has never been paired with this controller's key.

Supports the command codes 0x28 (DISCOVER_REQ), 0x2A (DISCOVER_SPE_REQ), and 0x2E (DISCOVER_ALT_REQ, alternate discovery). For 0x2A the payload is a 6-byte random nonce followed by a 6-byte HMAC computed over [cmd + nonce] using the supplied system key.

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID.
command	Discovery command code (0x28, 0x2A, or 0x2E).
dst	Destination node ID (broadcast or explicit).
low_power	True to set the LOW_POWER flag in CTRL1.
payload_enabled	True when the optional payload byte is enabled.
payload	Optional payload byte (only used when command requires a payload).
system_key	16-byte system key; only used for 0x2A HMAC computation.

Returns

true on success; false for unsupported command or missing key for 0x2A.

Definition at line 624 of file proto_commands.cpp.

Here is the call graph for this function:

create_execute_command()

bool esphome::home_io_control::create_execute_command	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power,
		CoverCommand	cmd,
		bool	silent )

Build a named-command execute frame (0x00) for STOP, FAVORITE, or VENT.

FORCE_OPEN is deliberately not handled here — unlike these three, it needs to know the device's wire-scale "fully open" position (0 or 100 depending on IoDevice::inverted, e.g. horizontal awnings), which this builder has no way to know. Use create_force_open() instead; see its comments for why.

Each maps to a specific wire encoding in the 6-byte special CMD_EXECUTE payload:

• STOP: main=0xD2, modifier=0x00
• FAVORITE: main=0xD8, modifier=0x00
• VENT: main=0xD8, modifier=0x03

This cleanly separates "move to position X" from "execute named action" without overloading a single numeric parameter.

FORCE_OPEN is NOT handled here — see create_force_open() instead. Unlike these three, it needs a device-specific "fully open" wire position (0 or 100 depending on inversion), which this generic dispatch has no way to supply; passing CoverCommand::FORCE_OPEN returns false.

Parameters

f	IoFrame to populate.
own	Controller's 3‑byte node ID (source address).
dst	Target device's 3‑byte node ID (destination address).
low_power	True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
cmd	Named command to execute (STOP, FAVORITE, or VENT).

Returns

true on success; false for invalid/unsupported command.

Parameters

silent

Use the silent (slower) travel profile. Honoured for FAVORITE only — STOP has no travel speed, and nothing has been captured for VENT.

Definition at line 285 of file proto_commands.cpp.

Here is the call graph for this function:

create_execute_position()

bool esphome::home_io_control::create_execute_position	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power,
		uint8_t	position,
		bool	silent = false )

Build a position execute command (0x00) to move a device to a numeric position.

Encodes a 0–100 position value into the standard 8-byte execute payload with originator, ACEI, and functional parameter fields. The wire encoding doubles the position value (0→0x00, 100→0xC8).

Parameters

f	IoFrame to populate.
own	Controller's 3‑byte node ID (source address).
dst	Target device's 3‑byte node ID (destination address).
low_power	True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
position	Desired position 0–100 (0=fully open, 100=fully closed).

Returns

true on success; false if position > 100.

Parameters

silent

Send the reference hub's "silent operation" extended block, which makes the motor travel more slowly. Applies to position moves only — STOP has no speed, and no capture yet shows what the toggle does to FAVORITE/VENT or tilt, so those are left alone rather than guessed at.

Definition at line 268 of file proto_commands.cpp.

Here is the call graph for this function:

create_execute_position_and_tilt()

bool esphome::home_io_control::create_execute_position_and_tilt	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power,
		uint8_t	position,
		uint8_t	tilt_percent )

Build a combined position-and-tilt execute command (0x00) — setClosureAndOrientation.

Build a combined position‑and‑tilt execute command (0x00).

Sets both the cover position and the slat angle atomically in one frame, corresponding to the protocol's setClosureAndOrientation use case.

Parameters

f	IoFrame to populate.
own	Controller node ID.
dst	Target device node ID.
low_power	True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
position	Desired position 0–100 (open→closed).
tilt_percent	0 = fully closed, 100 = fully open.

Returns

true on success; false if position exceeds limits.

Definition at line 539 of file proto_commands.cpp.

Here is the call graph for this function:

create_execute_tilt()

bool esphome::home_io_control::create_execute_tilt	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power,
		uint8_t	tilt_percent )

Build a tilt execute command (0x00) for devices that support slat angle control.

Build an execute‑tilt command (0x00) for slat angle control.

Parameters

f	IoFrame to populate.
own	Controller node ID.
dst	Target device node ID.
low_power	True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
tilt_percent	0 = fully closed, 100 = fully open.

Note

This uses the same command (0x00) as position control but with a different payload format indicating a tilt operation. The receiver infers tilt from the payload structure. Only devices that advertise tilt support (see device_supports_tilt in proto_frame.h) will honor this.

Returns

true on success.

Definition at line 520 of file proto_commands.cpp.

Here is the call graph for this function:

create_force_open()

bool esphome::home_io_control::create_force_open	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power,
		uint8_t	open_position )

Build a force-open execute frame (0x00): an ordinary position command to the device's wire-scale "fully open" value, sent at elevated ACEI priority (see EXECUTE_ACEI_FORCE_OPEN).

Build a force-open execute frame (0x00): move to the device's wire-scale "fully open" position at elevated ACEI priority (level 0, protection_human) instead of the usual user_high level — see EXECUTE_ACEI_FORCE_OPEN in proto_commands.cpp for why priority elevation, not a special position byte, is the protocol's real mechanism for getting past an environmental soft lock.

Takes the target position explicitly rather than assuming 0, because "fully open" is not always wire-position 0: IoDevice::inverted devices (e.g. horizontal awnings) have open/close swapped, so their fully-open wire position is 100. Hardcoding 0 here would, on a real inverted awning, target its already-*closed* resting position — a confirmed no-op rather than a lock bypass. The caller (execute_device_command_() in hub_operations.cpp) is responsible for resolving the correct value from the target IoDevice.

Parameters

f	IoFrame to populate.
own	Controller's 3‑byte node ID (source address).
dst	Target device's 3‑byte node ID (destination address).
low_power	True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
open_position	The device's wire-scale position value that means "fully open": 0 for ordinary devices, 100 for IoDevice::inverted ones (e.g. horizontal awnings) — the caller must resolve this from the target device, this builder does not have access to device state. Getting this wrong sends an ordinary, harmless-looking position command to the device's already-resting position instead of moving it anywhere.

Returns

true on success.

Note

The elevated-priority override has not yet been confirmed against a real active environmental lock.

Definition at line 333 of file proto_commands.cpp.

Here is the call graph for this function:

create_general_info3()

bool esphome::home_io_control::create_general_info3	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power )

Build a CMD_GET_GENERAL_INFO3 (0x58) request.

No payload — delegates to the shared create_no_payload_request() helper, the shape every device-info read uses.

No payload.

Shares the no-payload addressed-request shape with create_get_name(), create_get_info1() and create_get_info2() via a common file-local helper (proto_commands.cpp).

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID.
dst	Target device's 3-byte node ID.
low_power	True if target is battery/solar-powered (sets CTRL1_LOW_POWER).

Returns

true on success.

Definition at line 474 of file proto_commands.cpp.

create_get_info1()

bool esphome::home_io_control::create_get_info1	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power )

Build a CMD_GET_INFO1 (0x54) request. No payload. See proto_commands.h for the evidence note.

Build a CMD_GET_INFO1 (0x54) request.

No payload.

The request is field-observed — a real hub sends it — but no 0x55 answer has ever been captured. Diagnostic probe only; nothing in this codebase decodes a 0x55.

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID.
dst	Target device's 3-byte node ID.
low_power	True if target is battery/solar-powered (sets CTRL1_LOW_POWER).

Returns

true on success.

Definition at line 479 of file proto_commands.cpp.

create_get_info2()

bool esphome::home_io_control::create_get_info2	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power )

Build a CMD_GET_INFO2 (0x56) request. No payload. See proto_commands.h for the evidence note.

Build a CMD_GET_INFO2 (0x56) request.

No payload.

The request has never been captured on air; it rests on the even=request / odd=answer pairing rule, and on the fact that a 0x57 answer is captured (carrying a leading ASCII reference string plus the packed type/subtype bytes hub_status.cpp already reads at offsets 10/11).

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID.
dst	Target device's 3-byte node ID.
low_power	True if target is battery/solar-powered (sets CTRL1_LOW_POWER).

Returns

true on success.

Definition at line 484 of file proto_commands.cpp.

create_get_name()

bool esphome::home_io_control::create_get_name	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power )

Build a get-name request (0x50).

The device responds with its stored display name.

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID.
dst	Target device's 3-byte node ID.
low_power	True if target is battery/solar-powered (sets CTRL1_LOW_POWER).

Returns

true on success.

Definition at line 468 of file proto_commands.cpp.

create_get_status()

bool esphome::home_io_control::create_get_status	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power )

Build a get-status request (0x03). The device responds with its current position.

Build a get‑status request (0x03).

The device responds with its current position.

Parameters

f	IoFrame to populate.
own	Controller's 3‑byte node ID.
dst	Target device's 3‑byte node ID.
low_power	True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).

Returns

true on success.

Definition at line 464 of file proto_commands.cpp.

Here is the call graph for this function:

create_get_status_extended()

bool esphome::home_io_control::create_get_status_extended	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power,
		uint8_t	selector,
		uint8_t	block,
		uint8_t	function_id )

Build an extended CMD_PRIVATE (0x03) request with a selector/block pair — the shape real hubs use for both the tilt block (selector STATUS_TILT_SELECTOR) and the field-observed selector 0x80 (tests/corpus/captures/probe/multi_somfy_probe_extended_private_both_selectors.yaml), which this codebase has never decoded.

Build an extended CMD_PRIVATE (0x03) request with a selector/block pair.

block is the field-observed name for the byte that varies (0x00/0x01) for selector 0x80; create_get_status_tilt() below is this builder frozen at selector = STATUS_TILT_SELECTOR, block = 0x01. function_id defaults to PRIVATE_GET_POSITION_STATUS (0x03) — the only value ever seen on air in this shape; other values are diagnostic probes into an undecoded function ID.

The shape real hubs use for both the tilt block (selector STATUS_TILT_SELECTOR) and the field-observed selector 0x80 (tests/corpus/captures/probe/multi_somfy_probe_extended_private_both_selectors.yaml), which this codebase has never decoded. create_get_status_tilt() below is this builder frozen at selector = STATUS_TILT_SELECTOR, block = 0x01.

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID.
dst	Target device's 3-byte node ID.
low_power	True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
selector	Extended-status selector byte (data[1]).
block	Selector-specific block/index byte (data[2]) — the field-observed name for this byte is "N" for selector 0x80, where the corpus has only ever observed 0x00/0x01.
function_id	CMD_PRIVATE function ID at data[0]. Defaults to PRIVATE_GET_POSITION_STATUS (0x03) — the only value ever observed on air in this 4-byte extended shape. Other values are diagnostic probes: the shape 03 80 00 00 / 03 80 01 00 is field-observed from a real hub, but no other function ID has ever been seen in it.

Returns

true on success.

Definition at line 568 of file proto_commands.cpp.

Here is the call graph for this function:

create_get_status_tilt()

bool esphome::home_io_control::create_get_status_tilt	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power )

Build a tilt-aware get-status request (0x03) that returns the extended 16-byte tilt payload.

Build a tilt‑aware get‑status request (0x03 with extended payload) that returns the 16‑byte tilt block in the response.

Parameters

f	IoFrame to populate.
own	Controller node ID.
dst	Target device node ID.
low_power	True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).

Returns

true on success.

Definition at line 578 of file proto_commands.cpp.

Here is the call graph for this function:

create_identify()

bool esphome::home_io_control::create_identify	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power )

Build an authenticated device-identify request (0x1E).

Build an authenticated device-identify request (0x1E) that makes a device physically identify itself (brief jog / flash).

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID (source address).
dst	Target device's 3-byte node ID (destination address).
low_power	True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).

Note

The device may reply with CMD_ERROR_RESP instead of a dedicated identify response; callers should treat that reply as an expected, non-fatal outcome rather than a failure.

Returns

true on success.

Definition at line 497 of file proto_commands.cpp.

Here is the call graph for this function:

create_key_confirm()

bool esphome::home_io_control::create_key_confirm	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst )

Build a key-confirm frame (0x33) — device side, used only by the key-extraction responder.

Build a key-confirm frame (0x33) — the device's acknowledgement that it received and installed the system key, sent after decrypting a CMD_KEY_TRANSFER (0x32).

See proto_commands.h for the full contract and the real-capture cross-check.

Device-side counterpart to create_key_transfer(); used only by the key-extraction responder (see create_discover_resp() above for why this direction exists at all). No payload and END set, matching real devices' 0x33 in tests/corpus/captures/pairing/somfy_izymo_dimmer_pairing_full_sx1276.yaml, tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml, and (this project's own key-extraction responder against a real hub) tests/corpus/captures/pairing/velux_kig300_pairing_key_extraction_success.yaml — 0x33 closes the key-exchange sequence that CMD_KEY_INIT (0x31) opened with START.

Parameters

f	IoFrame to populate.
own	Our advertised (throwaway) node ID.
dst	Destination node ID (the hub that sent the key transfer).

Returns

true on success.

Definition at line 707 of file proto_commands.cpp.

Here is the call graph for this function:

create_key_init()

bool esphome::home_io_control::create_key_init	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst )

Build a key-init request (0x31) to start the pairing key exchange with a discovered device.

Build a key‑init request (0x31) to start pairing key exchange with a discovered device.

Parameters

f	IoFrame to populate.
own	Controller node ID.
dst	Discovered device node ID.

Returns

true on success.

Definition at line 727 of file proto_commands.cpp.

Here is the call graph for this function:

create_key_transfer()

bool esphome::home_io_control::create_key_transfer	(	IoFrame &	f,
		IoFrame &	old_frame,
		const uint8_t *	dst,
		const uint8_t *	src,
		const uint8_t	key[AES_KEY_SIZE],
		const uint8_t	challenge[HMAC_SIZE] )

Build a key-transfer frame (0x32) containing the system key encrypted with the transfer key.

Build a key‑transfer frame (0x32) containing the system key encrypted with the transfer key.

Parameters

f	IoFrame to populate.
old_frame	The key‑init frame (used to derive the encryption IV).
dst	Target device node ID.
src	Controller node ID.
key	The 16‑byte system key to transfer.
challenge	6‑byte challenge received from device in its 0x3C response.

Note

The system key is obfuscated via the XOR‑AES construction in crypt_key(). The transfer key (hardcoded in proto_frame.h) is the same for all IO‑Homecontrol devices worldwide; its purpose is to protect the system key in transit during initial pairing. Once transferred, the device uses the system key for all subsequent authenticated exchanges.

Returns

true on success.

Definition at line 735 of file proto_commands.cpp.

Here is the call graph for this function:

create_private2_read()

bool esphome::home_io_control::create_private2_read	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		uint8_t	modifier,
		bool	long_form,
		bool	low_power )

Build a CMD_PRIVATE2 (0x0C) request in either of the two field-observed shapes.

The payload is CMD_EXECUTE's POS_FAVORITE/POS_VENT_MODIFIER stored-position selector with the execution prefix stripped — modifier is that same selector byte (e.g. POS_VENT_MODIFIER for vent).

low_power is a separate parameter, not derived from long_form: the two captured fixtures (tests/corpus/captures/probe/multi_somfy_probe_private2_{long_form,short_form}.yaml) do carry CTRL1_LOW_POWER set on the long-form request and clear on the short-form ones, but that tracks the target device's power class in each capture (a solar shutter vs. a mains-powered switch), not the payload shape — the same relationship every other device-addressed builder in this file has to low_power. Deriving it from long_form would silently clear the flag on a short-form probe sent to a solar device.

The payload is CMD_EXECUTE's POS_FAVORITE/POS_VENT_MODIFIER stored-position selector with the execution prefix stripped. low_power is an explicit parameter like every other device-addressed builder in this file, not derived from long_form: the two captures this builder is pinned against happen to carry CTRL1_LOW_POWER set on the long-form request and clear on the short-form one, but that tracks each capture's target device's power class (solar shutter vs. mains switch), not the payload shape — see proto_commands.cpp for the full reasoning.

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID.
dst	Target device's 3-byte node ID.
modifier	The POS_FAVORITE/POS_VENT_MODIFIER-family selector byte to read back.
long_form	True for the 6-byte long form (data = POS_UNKNOWN, 0x00, 0x80, POS_FAVORITE, modifier, 0x00); false for the 4-byte short form (data = POS_FAVORITE, modifier, 0x00, 0x00).
low_power	True if target is battery/solar-powered (sets CTRL1_LOW_POWER).

Returns

true on success.

Definition at line 593 of file proto_commands.cpp.

Here is the call graph for this function:

create_private_function()

bool esphome::home_io_control::create_private_function	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power,
		uint8_t	function_id,
		uint8_t	sub_index )

Build a CMD_PRIVATE (0x03) request for an arbitrary function ID.

function_id = 0x06/0x09 reads battery state; create_get_status() below is this builder frozen at function_id = PRIVATE_GET_POSITION_STATUS (0x03), the only function ID this codebase has ever captured on its own wire.

function_id = 0x06 (battery-status) or 0x09 (battery-state) is reported elsewhere to read the CMD_PRIVATE_RESP reply as data[1]==0x60 => battery/solar powered, value = data[2]<<8|data[3]. Unverified here – both devices this project has probed are mains-powered and answered data[1]==0x00 (tests/corpus/captures/probe/somfy_awning_probe_private_fn_lr1121.yaml, tests/corpus/captures/probe/somfy_izymo_dimmer_probe_private_fn_lr1121.yaml). create_get_status() below is this builder frozen at function_id = PRIVATE_GET_POSITION_STATUS (0x03), the only function ID this codebase has ever captured on its own wire.

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID.
dst	Target device's 3-byte node ID.
low_power	True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER; the exchange layer then also uses the long wake-up preamble).
function_id	Private function ID (data[0] of the CMD_PRIVATE payload).
sub_index	Second payload byte (data[1]). Defaults to 0x00 — the only value any project has ever transmitted in this 3-byte form, and what every existing capture of ours contains. A non-zero value is a diagnostic probe into an undecoded parameter encoding: reference material describes a two-field (main parameter, functional parameter) addressing scheme here, but the field->byte mapping is not known — at least three encodings fit every payload observed to date equally well, because every one of them has both fields zero.

Returns

true on success.

Definition at line 454 of file proto_commands.cpp.

Here is the call graph for this function:

create_set_config1()

bool esphome::home_io_control::create_set_config1	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst )

Build a set-config command (0x6F) to tell the device to automatically send status updates when controlled by any remote (not just us).

Build a set‑config command (0x6F) telling the device to automatically send status updates when controlled by any remote.

Not all devices support this.

Parameters

f	IoFrame to populate.
own	Controller node ID.
dst	Target device node ID.

Note

This configures the device to emit CMD_STATUS_UPDATE (0x71) frames whenever it is controlled by any remote (including the paired controller). This enables HA to receive unsolicited position updates. The controller must still authenticate the status update using the inbound auth flow (hub_exchange.h).

Todo

Confirm on real hardware which device families actually honor this SetConfig1 payload and emit unsolicited status updates after pairing.

Returns

true on success.

Definition at line 858 of file proto_commands.cpp.

Here is the call graph for this function:

create_set_name()

bool esphome::home_io_control::create_set_name	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power,
		const uint8_t	payload[DEVICE_NAME_WRITE_PAYLOAD_SIZE] )

Build an authenticated set-name request (0x52) using a fixed zero-padded Latin-1 payload.

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID.
dst	Target device's 3-byte node ID.
low_power	True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
payload	Pre-validated fixed payload produced by encode_device_name_payload().

Returns

true on success.

Definition at line 488 of file proto_commands.cpp.

Here is the call graph for this function:

create_status_update_resp()

bool esphome::home_io_control::create_status_update_resp	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst )

Build a status-update acknowledgment (0x72).

Build a status‑update acknowledgment (0x72).

Sent after authenticating a device's status update. The response is sent on all 3 channels to ensure the device receives it.

Sent after authenticating a device's status update; broadcast on all 3 channels for reliability.

Parameters

f	IoFrame to populate.
own	Controller node ID.
dst	Device node ID that sent the update.

Returns

true on success.

Definition at line 846 of file proto_commands.cpp.

Here is the call graph for this function:

create_write_private()

bool esphome::home_io_control::create_write_private	(	IoFrame &	f,
		const uint8_t *	own,
		const uint8_t *	dst,
		bool	low_power,
		const uint8_t *	payload,
		size_t	payload_len )

Build a generic CMD_WRITE_PRIVATE (0x20) frame around a caller-supplied payload — the one builder behind every heating/climate function.

Build a generic CMD_WRITE_PRIVATE (0x20) frame carrying a caller-supplied payload.

Framing per the iohomecontrol reference implementation's forgePacket() (start=1, end=0) and the atlantic_thermor_exchange_write_private_param.yaml capture (frame 1: start, not end).

The single builder behind every heating/climate function (power, setpoint, mode, presence, window, midnight time-sync). The payload is produced by encode_heating_payload() in proto_heating.h; this builder only frames it. Framing is fixed by the reference implementation's forgePacket() (StartFrame=1, EndFrame=0, Protocol=0) and cross-checked against the real Atlantic Thermor exchange capture tests/corpus/captures/exchange/atlantic_thermor_exchange_write_private_param.yaml (frame 1: start=true, end=false). The device answers with CMD_WRITE_PRIVATE_ACK (0x21) after an authenticated 0x3C/0x3D leg the exchange engine handles transparently.

Parameters

f	IoFrame to populate.
own	Controller's 3-byte node ID (source address).
dst	Target device's 3-byte node ID (destination address).
low_power	True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER; the exchange layer then also uses the long wake-up preamble). Per-device, from the target's YAML low_power: class (ADR 0029) — not hardcoded.
payload	Payload bytes (from encode_heating_payload()).
payload_len	Payload length in bytes. Rejected if 0 or > FRAME_MAX_DATA_SIZE.

Returns

true on success; false if payload_len is out of range or set_cmd() fails.

Definition at line 509 of file proto_commands.cpp.

Here is the call graph for this function:

decode_1w_add_controller()

OneWayAddControllerDecodeError esphome::home_io_control::decode_1w_add_controller	(	const IoFrame &	frame,
		OneWayAdoptedKey &	out )

Decode a CMD_ONEWAY_ADD_CONTROLLER (0x30) frame into a recovered controller identity.

A 1W device broadcasts this frame while its key-copy gesture is active, handing its network's wrapped system key to whichever controller is listening (see CMD_ONEWAY_ADD_CONTROLLER's Doxygen in proto_constants.h). Three facts a future reader cannot re-derive from the code alone:

• The AES key that wraps the payload is the public TRANSFER_KEY (proto_constants.h), not the recovered system key — the system key is the output of unwrapping, not an input.
• The unwrap IV is derived only from the sender's own node address (frame.src), which is plaintext in the frame header — no secret or challenge is needed to begin unwrapping.
• The wrap is self-inverse (crypto::crypt_1w_key()'s XOR-with-AES-keystream construction), so the same call that would encrypt a plaintext key for transmission also decrypts an overheard ciphertext; there is no direction flag to get wrong.

Validates before decrypting rather than decrypting garbage: the 1W protocol bit must be set, the command must be CMD_ONEWAY_ADD_CONTROLLER, and the declared payload must be exactly the expected 20 bytes (enc_key[16] + man_id[1] + data[1] + sequence[2]) — any mismatch is rejected before crypto::crypt_1w_key() is ever called.

When frame.has_mac is true (the out-of-length MAC trailer modeled by IoFrame::mac, see proto_frame.h), the MAC is verified under the recovered key with span cmd + enc_key (17 bytes) — the only span CMD_ONEWAY_ADD_CONTROLLER authenticates (see crypto::create_1w_hmac()'s @warning). A verifying MAC is strong evidence the decryption recovered the correct key: it is the decisive self-check available at adoption time, before any device is ever commanded. A frame with no MAC is not an error — the reference implementation's own _p0x30 struct omits the MAC field entirely — so decoding still succeeds and out.mac_status simply reports NOT_PRESENT.

Pure function of the frame: no logging, no timers, no I/O (ADR 0005). Never transmits.

Parameters

frame	Parsed IoFrame, expected to be a CMD_ONEWAY_ADD_CONTROLLER 1W frame.
out	Output: recovered controller identity. Only meaningfully populated when the return value is NONE; left default-constructed (zeroed) otherwise.

Returns

NONE on success; otherwise the specific validation/decode failure.

Warning

out carries real key material once populated. See OneWayAdoptedKey's warning.

Definition at line 396 of file proto_codecs.cpp.

Here is the call graph for this function:

decode_1w_frame()

OneWayFrameInfo esphome::home_io_control::decode_1w_frame

(

const IoFrame &

frame

)

Decode a parsed 1W frame into a structured OneWayFrameInfo.

Extracts target device type from the broadcast address. For execute/activate-mode commands, also decodes originator, ACEI priority, and position/command intent.

Parameters

frame

Parsed IoFrame with CTRL0_PROTOCOL_1W set.

Returns

Populated OneWayFrameInfo.

Definition at line 331 of file proto_codecs.cpp.

Here is the call graph for this function:

decode_1w_main_intent()

void esphome::home_io_control::decode_1w_main_intent	(	uint8_t	main0,
		uint8_t	main1,
		char *	out,
		size_t	out_size )

Decode the "main" position/command bytes from a 1W execute payload.

1W remotes encode their command intent in a 2-byte main field:

• main[0]: position (0–200 mapped to 0–100%), or a special command code.
• main[1]: modifier byte (0x03 = ventilation for POS_FAVORITE).

Parameters

main0	First main byte (position or special code).
main1	Second main byte (modifier).
out	Buffer to write the decoded string into (e.g., "CLOSE", "position 75%").
out_size	Size of the output buffer.

Definition at line 258 of file proto_codecs.cpp.

decode_ctrl1_flags()

void esphome::home_io_control::decode_ctrl1_flags ( uint8_t ctrl1, char * out, size_t out_size )

inline

Render decoded CTRL1 flags into a short annotation string.

Parameters

ctrl1	The CTRL1 byte from a frame.
out	Buffer to write into (at least FRAME_LOG_FLAGS_BUFFER_SIZE bytes).
out_size	Size of the output buffer.

Definition at line 35 of file log_frame.h.

decode_device_name_payload()

std::string esphome::home_io_control::decode_device_name_payload	(	const uint8_t *	data,
		uint8_t	len )

Decode a device-name payload from IO-homecontrol's Latin-1 wire format into UTF-8.

Some devices prepend an extra byte before the first character and many pad the payload with trailing 0x00 or 0x20 bytes. This helper normalizes those quirks and truncates the result to fit DEVICE_NAME_BUFFER_SIZE - 1 bytes when copied into IoDevice::name.

Parameters

data	Raw payload pointer from CMD_GET_NAME_RESP.
len	Raw payload length in bytes.

Returns

Normalized UTF-8 name, or an empty string when the payload carries no usable characters.

Definition at line 88 of file proto_codecs.cpp.

decode_discovery_response()

DiscoveryResponseInfo esphome::home_io_control::decode_discovery_response	(	const IoFrame &	frame,
		IoDevice &	device,
		std::string &	device_id )

Decode a discovery-response payload (CMD_DISCOVER_RESP 0x29 or CMD_DISCOVER_SPE_RESP 0x2B — both carry the identical DISCOVERY_RESP_FULL_SIZE layout) into device metadata.

Pure: no logging, no side effects. Extended fields (manufacturer, flags, timestamp) are returned rather than logged so each caller can present them its own way. Sets device.node_id/type/subtype/inverted/position/target/is_stopped and device_id exactly as a discovery reply implies: type/subtype and inversion come from the packed metadata bytes when present, position/target default to the unknown sentinel, and the device is assumed stopped. Every field read is guarded on frame.data_len, so a short or truncated payload degrades gracefully instead of reading past the end.

Parameters

frame	Parsed discovery-response frame.
device	Output: device record populated from the frame.
device_id	Output: hex device ID string derived from frame.src.

Returns

Extended discovery fields (manufacturer/flags/timestamp) and length flags.

Definition at line 354 of file proto_codecs.cpp.

Here is the call graph for this function:

decode_packed_device_subtype()

uint8_t esphome::home_io_control::decode_packed_device_subtype

(

uint8_t

type_subtype

)

Decode a protocol-packed device subtype from the second metadata byte.

Parameters

type_subtype

Second metadata byte containing subtype in bits [5:0].

Returns

Manufacturer-specific subtype.

Definition at line 66 of file proto_device_model.cpp.

decode_packed_device_type()

DeviceType esphome::home_io_control::decode_packed_device_type	(	uint8_t	type_msb,
		uint8_t	type_subtype )

Decode a protocol-packed device type from two metadata bytes.

Parameters

type_msb	First metadata byte.
type_subtype	Second metadata byte containing the remaining type bits and subtype.

Returns

Decoded device type.

Definition at line 61 of file proto_device_model.cpp.

decode_position_report()

void esphome::home_io_control::decode_position_report	(	uint16_t	target_raw,
		uint16_t	current_raw,
		bool	is_stopped,
		float &	target,
		float &	position )

Decode target/current position values from a status frame.

Parameters

target_raw	16‑bit raw target value.
current_raw	16‑bit raw current value.
is_stopped	True if device reports stopped.
target	Output target position (0–100 or UNKNOWN_POSITION).
position	Output current position (0–100 or UNKNOWN_POSITION).

Definition at line 74 of file proto_device_model.cpp.

decode_tilt_report()

float esphome::home_io_control::decode_tilt_report

(

uint16_t

tilt_raw

)

Decode tilt angle from raw 16‑bit value.

Parameters

tilt_raw

Raw tilt value from status frame.

Returns

Tilt percentage (0 = closed, 100 = open) or UNKNOWN_POSITION.

Definition at line 107 of file proto_device_model.cpp.

decode_uart_probe()

uint8_t esphome::home_io_control::decode_uart_probe	(	const uint8_t *	raw,
		uint8_t	raw_len,
		uint8_t	bit_offset,
		uint8_t *	decoded,
		uint8_t	decoded_max_len )

Decode a raw UART‑encoded bitstream into bytes.

Decode a UART-encoded bitstream from the given bit offset.

IO‑Homecontrol uses a UART‑like encoding over the air: each byte is represented by a 10‑bit sequence (start bit 0, 8 data bits LSB‑first, stop bit 1). This function slides a window across the raw bitstream and attempts to recover the original bytes. It stops when the sync pattern (0 followed by 1) is not found.

Parameters

raw	Raw bytes from the radio buffer.
raw_len	Number of raw bytes available.
bit_offset	Initial bit position to start decoding (probe offset).
decoded	Output buffer for decoded bytes.
decoded_max_len	Capacity of decoded buffer.

Returns

Number of bytes successfully decoded.

Definition at line 47 of file radio_soft_phy.cpp.

default_inverted_for_type()

bool esphome::home_io_control::default_inverted_for_type

(

DeviceType

type

)

Determine whether a device type has inverted position mapping by default.

Parameters

type	Device type.

Returns

true for horizontal awnings; false otherwise.

Definition at line 44 of file proto_device_model.cpp.

device_capability_class()

DeviceCapabilityClass esphome::home_io_control::device_capability_class

(

DeviceType

type

)

Map a raw IO‑Homecontrol type to the closest ESPHome/Home Assistant entity family.

Parameters

type	Raw device type.

Returns

Capability class (COVER, LIGHT, SWITCH, etc.).

Definition at line 225 of file proto_device_model.cpp.

device_capability_class_name()

const char * esphome::home_io_control::device_capability_class_name

(

DeviceType

type

)

Get a human‑readable name for a capability class.

Parameters

type	Device type (unused, kept for signature compatibility).

Returns

String like "cover", "light", "switch", "unknown".

Definition at line 274 of file proto_device_model.cpp.

Here is the call graph for this function:

device_name_validation_error_description()

const char * esphome::home_io_control::device_name_validation_error_description

(

DeviceNameValidationError

error

)

Return a human-readable explanation for a device-name validation result.

Parameters

error

Validation result.

Returns

Short message suitable for logs and Home Assistant action events.

Definition at line 179 of file proto_codecs.cpp.

device_name_validation_error_name()

const char * esphome::home_io_control::device_name_validation_error_name

(

DeviceNameValidationError

error

)

Return a stable symbolic name for a device-name validation result.

Parameters

error

Validation result.

Returns

Uppercase symbolic name.

Definition at line 162 of file proto_codecs.cpp.

device_operation_profile_name()

const char * esphome::home_io_control::device_operation_profile_name

(

DeviceType

type

)

Human‑readable operation profile name for a device type.

Used for logging and diagnostics.

Parameters

type	Device type.

Returns

String such as "cover_position", "cover_position_tilt", "binary_on_off", "lock", etc.

Definition at line 388 of file proto_device_model.cpp.

Here is the call graph for this function:

device_rssi_ema_dbm()

int16_t esphome::home_io_control::device_rssi_ema_dbm ( const IoDevice & dev )

inline

A device's smoothed RSSI in whole dBm.

Parameters

dev	Device record to read.

Returns

Rounded EMA in dBm, or RSSI_UNKNOWN_DBM when no sample has been recorded yet.

Definition at line 375 of file proto_device_model.h.

Here is the call graph for this function:

device_supports_binary_control()

bool esphome::home_io_control::device_supports_binary_control

(

DeviceType

type

)

Does this device type support binary on/off control?

Parameters

type	Device type.

Returns

true for lights and switches.

Definition at line 300 of file proto_device_model.cpp.

Here is the call graph for this function:

device_supports_climate_control()

bool esphome::home_io_control::device_supports_climate_control

(

DeviceType

type

)

Does this device type support 2W climate/heating control (CMD_WRITE_PRIVATE 0x20)?

The single capability gate for the heating send path and the climate entity: true exactly when device_capability_class(type) is DeviceCapabilityClass::CLIMATE (HEATING_TEMPERATURE_INTERFACE, EXTERIOR_HEATING, HEAT_PUMP). There is deliberately no per-device-type or per-vendor branch anywhere downstream.

Parameters

type	Device type.

Returns

true for climate-class devices.

Definition at line 309 of file proto_device_model.cpp.

Here is the call graph for this function:

device_supports_lock_control()

bool esphome::home_io_control::device_supports_lock_control

(

DeviceType

type

)

Does this device type support binary lock/unlock control via execute commands?

Parameters

type	Device type.

Returns

true for lock devices.

Definition at line 305 of file proto_device_model.cpp.

Here is the call graph for this function:

device_supports_position_control()

bool esphome::home_io_control::device_supports_position_control

(

DeviceType

type

)

Does this device type support precise position control (0–100)?

Parameters

type	Device type.

Returns

true for cover‑family devices.

Definition at line 296 of file proto_device_model.cpp.

Here is the call graph for this function:

device_supports_status_requests()

bool esphome::home_io_control::device_supports_status_requests

(

DeviceType

type

)

Does this device type support status request commands (0x03)?

Parameters

type	Device type.

Returns

true for covers, binary devices, and lock devices.

Definition at line 313 of file proto_device_model.cpp.

Here is the call graph for this function:

device_supports_tilt()

bool esphome::home_io_control::device_supports_tilt

(

DeviceType

type

)

Does this device type support tilt (slat angle) control?

Parameters

type	Device type.

Returns

true for venetian blinds, blinds, external venetian blinds, louvre blinds.

Definition at line 318 of file proto_device_model.cpp.

device_supports_vent()

bool esphome::home_io_control::device_supports_vent

(

DeviceType

type

)

Does this device type support the ventilation position command?

The ventilation command moves window-type actuators to a predefined partially-open position suitable for air exchange without fully opening.

Parameters

type	Device type.

Returns

true for WINDOW_OPENER and VENTILATION_POINT.

Definition at line 353 of file proto_device_model.cpp.

device_type_name()

const char * esphome::home_io_control::device_type_name

(

DeviceType

type

)

Convert a DeviceType to a lowercase string identifier.

Parameters

type	Device type enum.

Returns

Null‑terminated string name (e.g., "roller_shutter").

Definition at line 113 of file proto_device_model.cpp.

discovery_att_class()

uint8_t esphome::home_io_control::discovery_att_class ( uint8_t flags )

inline

Extract the ATT class field from a discovery response's Multi Information Byte.

Parameters

flags

Multi Information Byte (data[DISCOVERY_RESP_FLAGS_OFFSET]).

Returns

ATT class value (0–3); pass to att_class_name() for a human-readable string.

Definition at line 620 of file proto_constants.h.

discovery_command_from_string()

std::optional< DiscoveryCommand > esphome::home_io_control::discovery_command_from_string

(

const std::string &

value

)

Parse a discovery command string (e.g., "0x28") into the enum.

Parameters

value

String to parse.

Returns

Discovery command enum, or std::nullopt on invalid input.

Definition at line 158 of file tuning_config.cpp.

discovery_command_to_string()

std::string esphome::home_io_control::discovery_command_to_string

(

DiscoveryCommand

cmd

)

Format a discovery command enum for YAML/logs.

Parameters

cmd	Discovery command enum.

Returns

Lowercase hex string such as "0x28".

Definition at line 171 of file tuning_config.cpp.

discovery_commands_to_csv()

std::string esphome::home_io_control::discovery_commands_to_csv

(

const std::vector< DiscoveryCommand > &

commands

)

Format the ordered discovery command list as a UI/preset option string.

Matches the comma-separated select option labels (no brackets) so a boot-time snapshot round-trips to a selectable dropdown value.

Parameters

commands

Ordered list of discovery commands.

Returns

Comma-separated list such as "0x28,0x2E" (empty string when the list is empty).

Definition at line 177 of file tuning_config.cpp.

Here is the call graph for this function:

discovery_commands_to_string()

std::string esphome::home_io_control::discovery_commands_to_string

(

const std::vector< DiscoveryCommand > &

commands

)

Format the ordered discovery command list for logs.

Parameters

commands

Ordered list of discovery commands.

Returns

Bracketed comma-separated list such as "[0x28,0x2E]".

Definition at line 187 of file tuning_config.cpp.

Here is the call graph for this function:

discovery_destination_to_string()

std::string esphome::home_io_control::discovery_destination_to_string	(	bool	destination_auto,
		const uint8_t	destination[NODE_ID_SIZE] )

Format a destination option for YAML/logs.

Parameters

destination_auto	Whether automatic destination mapping is used.
destination	Explicit 3-byte destination when auto is false.

Returns

"auto" or a hex address such as "0x00003B".

Definition at line 208 of file tuning_config.cpp.

discovery_payload_to_string()

std::string esphome::home_io_control::discovery_payload_to_string	(	bool	payload_enabled,
		uint8_t	payload )

Format a payload option for YAML/logs.

Parameters

payload_enabled	Whether the optional payload is enabled.
payload	The payload byte when enabled.

Returns

"none" or a hex byte such as "0x00".

Definition at line 216 of file tuning_config.cpp.

discovery_power_save_mode()

uint8_t esphome::home_io_control::discovery_power_save_mode ( uint8_t flags )

inline

Extract the power save mode field from a discovery response's Multi Information Byte.

Parameters

flags

Multi Information Byte (data[DISCOVERY_RESP_FLAGS_OFFSET]).

Returns

Power save mode value (0–1); pass to power_save_mode_name() for a human-readable string.

Definition at line 627 of file proto_constants.h.

effective_enrollment_classes()

std::array< DeviceType, 3 > esphome::home_io_control::effective_enrollment_classes ( const OneWayControllerIdentity & identity )

inline

The device classes this identity's 0x30 enrollment sweep will actually target.

Parameters

identity

The controller identity.

Returns

enrollment_classes when the identity overrode it (any entry non-UNKNOWN), else the manufacturer profile's list. UNKNOWN entries are skipped by the caller.

Definition at line 132 of file oneway_controller.h.

Here is the call graph for this function:

effective_execute_acei()

uint8_t esphome::home_io_control::effective_execute_acei ( const OneWayControllerIdentity & identity )

inline

The ACEI byte a given identity will put on air for a 1W EXECUTE frame.

Parameters

identity

The controller identity.

Returns

execute_acei when overridden (non-zero), else the manufacturer's profile default.

Definition at line 143 of file oneway_controller.h.

Here is the call graph for this function:

effective_is_stopped()

bool esphome::home_io_control::effective_is_stopped ( const IoDevice & dev )

inline

Whether a consumer should treat the device as at rest, prediction first.

Parameters

dev	Device record to read.

Returns

The predicted movement state when one stands, otherwise dev.is_stopped.

Definition at line 397 of file proto_device_model.h.

effective_target()

float esphome::home_io_control::effective_target ( const IoDevice & dev )

inline

The main-position target a consumer should act on: the prediction when one stands, otherwise the device's own last reported target.

Parameters

dev	Device record to read.

Returns

The predicted target when set, otherwise dev.target.

Definition at line 383 of file proto_device_model.h.

effective_tilt()

float esphome::home_io_control::effective_tilt ( const IoDevice & dev )

inline

The slat angle a consumer should act on, prediction first.

Parameters

dev	Device record to read.

Returns

The predicted tilt when set, otherwise dev.tilt.

Definition at line 390 of file proto_device_model.h.

encode_broadcast_address()

void esphome::home_io_control::encode_broadcast_address	(	DeviceType	type,
		uint8_t	out[NODE_ID_SIZE] )

Encode a device type into its typed-broadcast destination address — the exact inverse of broadcast_target_type(), kept immediately beside it so the pair cannot drift apart.

The class occupies bits [9:2] and therefore spans two bytes: out[0] is always 0, out[1] = raw >> DEVICE_TYPE_LOW_BITS_SHIFT carries the high bits, and out[2] = (raw << DEVICE_TYPE_HIGH_BITS_SHIFT) | DEVICE_SUBTYPE_MASK carries the low bits plus the all-ones subtype field that makes the address a broadcast ("any subtype of this class"). A single-byte encoding looks right for classes 0–3 and silently produces the wrong class from 4 upward — e.g. the light class (0x06) encodes to 00 01 BF, not 00 00 BF. This is the addressing primitive 1W execute frames use: 1W commands a device class, never an individual node, so this is the only destination a 1W builder ever needs.

Parameters

type	Device class to address.
out	Output: 3-byte typed-broadcast destination address.

Definition at line 251 of file proto_codecs.cpp.

encode_device_name_payload()

DeviceNameValidationError esphome::home_io_control::encode_device_name_payload	(	const std::string &	name,
		uint8_t	payload[DEVICE_NAME_WRITE_PAYLOAD_SIZE],
		std::string &	normalized_name )

Validate and encode a user-supplied UTF-8 device name into the fixed Latin-1 write payload.

The outbound payload is a fixed 16-byte field: up to 15 Latin-1 characters followed by trailing zero padding. Leading and trailing ASCII whitespace are trimmed before validation so write-back verification against the device's padded storage is deterministic.

Parameters

name	User-supplied UTF-8 device name.
payload	Output buffer for the fixed write payload (16 bytes, zero-padded on success).
normalized_name	Output normalized UTF-8 name used for later verification/logging.

Returns

Validation status indicating success or the reason the name cannot be written.

Definition at line 107 of file proto_codecs.cpp.

Here is the call graph for this function:

encode_heating_payload()

size_t esphome::home_io_control::encode_heating_payload	(	HeatingFunction	fn,
		float	value,
		uint8_t	out[HEATING_PAYLOAD_MAX_SIZE] )

Encode one heating function into a CMD_WRITE_PRIVATE (0x20) payload.

Table-driven: a single constexpr descriptor table supplies the direction byte, register-low byte and value kind per function, so there is no copy-pasted per-function builder. value is interpreted by function:

• SET_TEMPERATURE: degrees Celsius, must lie within [HEATING_TEMP_MIN_C, HEATING_TEMP_MAX_C]; encoded as a 16-bit little-endian value in tenths of a degree, round-half-away-from-zero(10 * value) (AtlanticThermor/README.md's 0x0103 / 0x0130 rows). iohcCozyDevice2W.cpp:125-128 only writes the low byte and truncates; this codec writes both bytes and rounds, deliberately.
• SET_MODE: a HeatingMode value widened to float (e.g. float(HeatingMode::MANUAL)); must be exactly one of AUTO / MANUAL / PROG / OFF.
• SET_PRESENCE: 0 (absent) or 1 (present) (iohcCozyDevice2W.cpp:198-199).
• SET_WINDOW: 0 (closed) or 1 (open / frost protection) (iohcCozyDevice2W.cpp:221-222).
• POWER_ON / MIDNIGHT_SYNC: value is ignored. Out-of-range, non-integral (for enum/binary kinds) or non-finite input is rejected with a 0 return — a byte derived from a truncating or wrapping cast is never emitted.

  Parameters

  fn	Function to encode.
  value	Function-specific value (see above).
  out	Output buffer of HEATING_PAYLOAD_MAX_SIZE bytes.

  Returns

  Number of payload bytes written (4, 5 or 6), or 0 on invalid input.

Definition at line 103 of file proto_heating.cpp.

encode_packed_device_type()

void esphome::home_io_control::encode_packed_device_type	(	DeviceType	type,
		uint8_t	subtype,
		uint8_t &	type_msb,
		uint8_t &	type_subtype )

Encode a DeviceType/subtype pair into the two-byte packed metadata format used by discovery responses — the inverse of decode_packed_device_type()/decode_packed_device_subtype().

Parameters

type	Device type to encode.
subtype	Manufacturer-specific subtype; only bits [5:0] are used.
type_msb	Output: first metadata byte.
type_subtype	Output: second metadata byte (top 2 type bits + 6-bit subtype).

Definition at line 68 of file proto_device_model.cpp.

find_crc_valid_frame()

std::pair< uint8_t, uint8_t > esphome::home_io_control::find_crc_valid_frame ( const uint8_t * decoded, uint8_t decoded_len )

static

Try to find a CRC-valid IO-Homecontrol frame within a decoded UART byte stream.

Parameters

decoded	Decoded byte buffer from UART probe.
decoded_len	Number of decoded bytes.

Returns

Frame start index and length if found, or {0, 0} if no valid frame.

Definition at line 150 of file radio_soft_phy.cpp.

Here is the call graph for this function:

find_tuning_number()

const TuningNumberParam * esphome::home_io_control::find_tuning_number

(

const std::string &

name

)

Look up a numeric tuning parameter by name; returns nullptr if unknown.

Definition at line 185 of file tuning_registry.cpp.

find_tuning_select()

const TuningSelectParam * esphome::home_io_control::find_tuning_select

(

const std::string &

name

)

Look up a select tuning parameter by name; returns nullptr if unknown.

Definition at line 193 of file tuning_registry.cpp.

find_uart_probe()

UartProbeResult esphome::home_io_control::find_uart_probe	(	const uint8_t *	raw,
		uint8_t	raw_len )

Search raw RX buffer for the best CRC-validated IO-Homecontrol frame.

Definition at line 181 of file radio_soft_phy.cpp.

Here is the call graph for this function:

format_device_type_diagnostic()

std::string esphome::home_io_control::format_device_type_diagnostic

(

DeviceType

type

)

Human-readable device type string for diagnostics, including the raw numeric value.

Parameters

type	Device type.

Returns

String such as "horizontal_awning (0x10)", or the raw hex form ("0x1A") when the type has no symbolic name.

Definition at line 414 of file proto_device_model.cpp.

Here is the call graph for this function:

format_device_type_for_yaml()

std::string esphome::home_io_control::format_device_type_for_yaml

(

DeviceType

type

)

Build the YAML value for a device's io_device_type key.

Parameters

type	Device type.

Returns

A quoted symbolic name (e.g. "horizontal_awning") when one exists, otherwise the raw hex form (e.g. 0x1A) for a type with no YAML alias.

Definition at line 423 of file proto_device_model.cpp.

Here is the call graph for this function:

format_hex_byte()

std::string esphome::home_io_control::format_hex_byte ( uint8_t value )

static

Format a byte as two uppercase hex digits, no prefix.

Named neutrally rather than after any one caller: used for CMD_ERROR_RESP result codes, probe reply/index command bytes, and sweep index values alike – none of those is a "result code" except the first.

Definition at line 333 of file management_actions.cpp.

format_oneway_command_report()

std::string esphome::home_io_control::format_oneway_command_report

(

const OneWayCommandReport &

report

)

Build the sensor string for one command report.

Pure and free-standing so the wording is unit-testable: the host ESP_LOG stub discards its arguments, so a formatter buried in a publish call could not be asserted on at all.

Parameters

report

The attempt to describe.

Returns

Human-readable summary, e.g. STOP -> awning seq 1234 or STOP -> awning seq 1234 (not sent).

Definition at line 12 of file platform_oneway_entities.cpp.

Here is the call graph for this function:

format_position()

std::string esphome::home_io_control::format_position ( float pos )

inline

Format a position float as a human‑readable string (e.g.

"50%", "unknown").

Parameters

pos	Position value (0–100 or UNKNOWN_POSITION).

Returns

String like "50%" or "unknown".

Definition at line 1157 of file hub_core.h.

format_scan_reply_line()

std::string esphome::home_io_control::format_scan_reply_line ( const ScanResponder & responder, const std::string & device_id, bool known )

static

Format one roll-call responder's report line(s).

Known responders get a single summary line; unknown responders get the same summary line plus a lead-in sentence and a ready-to-paste YAML block (or, if the decoded type has no ESPHome platform, an explanatory line instead of a blank) — the same "paste this in" framing a successful pairing prints.

Parameters

responder	Decoded responder record.
device_id	Hex device ID string for this responder, rebuilt from responder.src.
known	True if this device is already registered on this hub.

Definition at line 943 of file management_actions.cpp.

Here is the call graph for this function:

frame_carries_mac_trailer()

bool esphome::home_io_control::frame_carries_mac_trailer

(

uint8_t

cmd

)

Whether wire frames for a command carry the out-of-length MAC trailer described on IoFrame::has_mac/IoFrame::mac.

This exists because CTRL0's 5-bit length field cannot describe every command's declared payload plus a 6-byte authenticator in one span — one command's authenticator is carried outside the declared length instead (see the command's own Doxygen in proto_constants.h for why). parse() consults this before it will accept the wider declared_len + HMAC_SIZE buffer shape for a given command, so an unrelated frame that merely happens to arrive with 6 extra trailing bytes is never mistaken for a trailer-bearing one — only a command that genuinely carries a trailer gets the wider shape considered at all.

Parameters

cmd	Command byte (IoFrame::cmd, or the raw byte at FRAME_CMD_OFFSET in a wire buffer).

Returns

true if cmd's wire frames carry the mac trailer after the declared length.

Definition at line 107 of file proto_frame.cpp.

frame_length()

uint8_t esphome::home_io_control::frame_length

(

const IoFrame &

f

)

Get total frame length from ctrl0.

Parameters

f	Parsed frame.

Returns

Length in bytes.

Definition at line 103 of file proto_frame.cpp.

has_execute_acei_override()

bool esphome::home_io_control::has_execute_acei_override ( const OneWayControllerIdentity & identity )

inline

Whether this identity's ACEI comes from an explicit execute_acei: rather than the profile.

Parameters

identity

The controller identity.

Returns

true when execute_acei: was set (non-zero) and overrides the manufacturer profile default.

Definition at line 151 of file oneway_controller.h.

has_reached_target_position()

bool esphome::home_io_control::has_reached_target_position	(	float	target,
		float	position )

Has the device reached its target within tolerance?

Parameters

target	Target position (0–100 or UNKNOWN_POSITION).
position	Current position (0–100 or UNKNOWN_POSITION).

Returns

true if positions match within STATUS_POS_TOLERANCE_RAW.

Definition at line 100 of file proto_device_model.cpp.

heating_function_name()

const char * esphome::home_io_control::heating_function_name

(

HeatingFunction

fn

)

Stable lowercase name for a heating function ("power_on", "set_temperature", ...).

Parameters

fn

Function.

Returns

Null-terminated string; "unknown" for an out-of-range value.

Definition at line 85 of file proto_heating.cpp.

hex_nibble()

int esphome::home_io_control::hex_nibble ( char ch )

static

Definition at line 22 of file proto_frame.cpp.

hex_to_bytes()

bool esphome::home_io_control::hex_to_bytes	(	const std::string &	hex,
		uint8_t *	out,
		uint8_t	len )

Convert a hex string (e.g., "123ABC") to a byte array.

Parameters

hex	Hex string (must be exactly len*2 characters).
out	Output buffer (at least len bytes).
len	Number of bytes to produce.

Returns

true on success; false if hex length mismatch or non‑hex characters.

Definition at line 31 of file proto_frame.cpp.

Here is the call graph for this function:

init_frame()

void esphome::home_io_control::init_frame	(	IoFrame &	f,
		bool	is_2w = true,
		bool	start = false,
		bool	end = false,
		bool	low_power = false )

Initialize an IoFrame header (ctrl0/ctrl1) with flags.

Note: CTRL1_ACK is NOT automatically set on outbound frames. Some real-world devices reject frames with unexpected CTRL1 bits, causing total communication failure. The ACK constant is retained for inbound frame parsing and logging only.

Parameters

f	Frame to initialize.
is_2w	True for 2‑way (default), false for 1‑way.
start	Set START flag (first frame in exchange).
end	Set END flag (final frame in exchange).
low_power	Set LOW_POWER flag.

Definition at line 70 of file proto_frame.cpp.

is_end()

bool esphome::home_io_control::is_end

(

const IoFrame &

f

)

Check END flag.

Parameters

f	Parsed frame.

Returns

true if END flag is set.

Definition at line 105 of file proto_frame.cpp.

is_known_io_command()

bool esphome::home_io_control::is_known_io_command

(

uint8_t

cmd

)

This list missing CMD_GET_GENERAL_INFO3_RESP (0x59) is exactly what turned a real Q2 probe reply into a false "no reply" timeout on real hardware (2026-08-16); the same audit also found CMD_IDENTIFY and CMD_WRITE_PRIVATE/CMD_WRITE_PRIVATE_ACK missing, unrelated to that probe but affecting the already-shipped identify_device() action (and climate writes) on SX1262/LR1121.

Check if a command ID is one of the known IO-Homecontrol commands.

Add every new opcode this codebase sends a request for, or expects a reply to, here as well as in proto_constants.h. Deliberately excludes CMD_UNKNOWN4A_REQ (0x4A, see ADR 0024) — recognizing a received 0x4A would not violate the "never transmitted" rule, but nothing in this codebase currently sends anything that would draw one, so there is no exchange for it to unblock; CMD_UNKNOWN4A_RESP (0x4B) is included because it is a plausible reply to CMD_GET_GENERAL_INFO3 (0x58), which this codebase does send. Declared in radio_soft_phy.h so tests can enumerate every accepted command directly.

This is a gate, not a directory: find_uart_probe() only accepts a CRC-valid candidate whose cmd passes this check (or whose CTRL0_PROTOCOL_1W bit is set), so a command missing here makes every SX1262/LR1121 reception of that opcode silently unrecoverable on this software PHY — the frame is on air, its CRC matches, and it still never reaches the parser. Exposed (out of radio_soft_phy.cpp's anonymous namespace) so tests can iterate every accepted command directly instead of hand-maintaining a parallel list that can drift out of sync with this one.

Parameters

cmd	Command byte.

Returns

true if cmd matches a known command constant.

Definition at line 83 of file radio_soft_phy.cpp.

is_limitation_result()

bool esphome::home_io_control::is_limitation_result

(

uint8_t

result

)

Check whether a result code represents an environmental or control limitation.

Parameters

result

Result byte from CMD_ERROR_RESP data[0].

Returns

true when the response reports a limitation rather than a generic execution error.

Definition at line 458 of file proto_constants.cpp.

is_start()

bool esphome::home_io_control::is_start

(

const IoFrame &

f

)

Check START flag.

Parameters

f	Parsed frame.

Returns

true if START flag is set.

Definition at line 104 of file proto_frame.cpp.

lr1121_bandwidth_from_string()

std::optional< LR1121RxBandwidth > esphome::home_io_control::lr1121_bandwidth_from_string

(

const std::string &

value

)

Convert a YAML LR1121 bandwidth string to the enum value.

Parameters

value

YAML string such as "117.3" or "39.0kHz".

Returns

Bandwidth enum, or std::nullopt on invalid input.

Definition at line 152 of file tuning_config.cpp.

Here is the call graph for this function:

lr1121_bandwidth_table()

BandwidthTableView esphome::home_io_control::lr1121_bandwidth_table

(

)

The LR1121 RX-bandwidth option table (see sx1262_bandwidth_table()).

Definition at line 111 of file tuning_config.cpp.

lr1121_bandwidth_to_khz()

float esphome::home_io_control::lr1121_bandwidth_to_khz

(

LR1121RxBandwidth

bw

)

Convert an LR1121 bandwidth enum to the numeric kHz value used in YAML/logs.

Parameters

bw	LR1121 bandwidth enum.

Returns

Floating-point kHz value (39.0, 46.9, 58.6, 78.2, 117.3, 156.2, or 187.2).

Definition at line 143 of file tuning_config.cpp.

Here is the call graph for this function:

lr1121_bandwidth_to_string()

std::string esphome::home_io_control::lr1121_bandwidth_to_string

(

LR1121RxBandwidth

bw

)

Format an LR1121 bandwidth enum as its YAML/UI option string (bare kHz number).

Parameters

bw	LR1121 bandwidth enum.

Returns

Bandwidth rendered with one decimal place (e.g. "117.3").

Definition at line 148 of file tuning_config.cpp.

Here is the call graph for this function:

lr1121_bootloader_is_lr1121()

bool esphome::home_io_control::lr1121_bootloader_is_lr1121 ( uint16_t bootloader_version )

nodiscardconstexpr

Returns

true if bootloader_version is one of the two bootloader versions an LR1121 (as opposed to an LR1120 or LR1110) can report.

Definition at line 62 of file lr1121_firmware_decisions.h.

lr1121_bootloader_mismatch_kind()

BootloaderMismatch esphome::home_io_control::lr1121_bootloader_mismatch_kind ( uint16_t target_fw, uint16_t bootloader_version )

nodiscardconstexpr

Classify a bootloader/target mismatch by direction; see BootloaderMismatch.

Definition at line 162 of file lr1121_firmware_decisions.h.

Here is the call graph for this function:

lr1121_bootloader_supports_target()

BootloaderSupport esphome::home_io_control::lr1121_bootloader_supports_target ( uint16_t target_fw, uint16_t bootloader_version )

nodiscardconstexpr

Look up whether target_fw is known to require bootloader_version.

A target absent from LR1121_KNOWN_BOOTLOADER_REQUIREMENTS is UNKNOWN_TARGET, never UNSUPPORTED — the table is a snapshot of what Semtech had published when this file was last updated, not an allow-list; a future firmware version this build has never heard of must not be rejected on that basis alone (see lr1121_flash_decision()'s three-way rule).

Definition at line 123 of file lr1121_firmware_decisions.h.

lr1121_bootloader_upgrade_path()

BootloaderUpgradePath esphome::home_io_control::lr1121_bootloader_upgrade_path ( bool block_present, bool bootloader_version_known, uint16_t bootloader_version, uint16_t loader_fw, uint16_t target_fw )

nodiscardconstexpr

Whether the three-stage bootloader upgrade is applicable for the current cached state.

A post-filter, consulted only when lr1121_flash_decision() has already returned REJECT_BOOTLOADER_TOO_OLD – it never runs earlier and never changes that function's verdict (see this header's file comment and lr1121_flash_decision()'s doc comment). The evaluation order below is the specification – each rule exists to close a specific way an irreversible write could be justified on insufficient evidence:

1. !block_present -> NOT_APPLICABLE – feature not built in.
2. !bootloader_version_known -> NOT_APPLICABLE – an unknown current bootloader cannot justify an irreversible write. Note Lr1121FirmwareUpdateController::run_flash_sequence_() adopts a fresh reading at flash time for the ordinary transceiver path; that allowance must not extend to here.
3. bootloader_version doesn't identify an LR1121 -> NOT_APPLICABLE – REJECT_WRONG_CHIP owns wrong-chip messaging, this function does not duplicate it.
4. loader_fw != bootloader_version -> NOT_APPLICABLE – Semtech's equality rule for the loader image (see LR1121_LOADER_2100); also the "chip is already on 0x2101" case, since no 0x2101-chip can equal the 0x2100 loader.
5. target not in the compatibility table (required == 0) -> BLOCKED_UNKNOWN_TARGET – never gamble an irreversible write on an unrecognised target.
6. required == bootloader_version -> NOT_APPLICABLE – no upgrade needed.
7. required > bootloader_version -> AVAILABLE – the one path that proceeds.
8. else (required < bootloader_version) -> BLOCKED_BOOTLOADER_NEWER – a downgrade. The 0x8101 report includes an anti-rollback check, whose exact semantics Semtech does not document, but which most likely makes this permanently impossible; ADR 0021 records how far that is inference.

   Parameters

   block_present	Whether a bootloader: sub-block is configured (the build flag).
   bootloader_version_known	Whether the boot-time excursion successfully read a bootloader version – same "unknown is never evidence" sentinel rule as lr1121_flash_decision().
   bootloader_version	Bootloader version read at boot; meaningless if !bootloader_version_known.
   loader_fw	Version parsed from the bootloader: sub-block's loader source: image.
   target_fw	Configured target firmware version (0 if unknown).

Definition at line 211 of file lr1121_firmware_decisions.h.

Here is the call graph for this function:

lr1121_chip_family_for_bootloader()

const char * esphome::home_io_control::lr1121_chip_family_for_bootloader ( uint16_t bootloader_version )

nodiscardconstexpr

Human-readable chip family for a bootloader version that is not one of the two LR1121 values above, for an actionable REJECT_WRONG_CHIP message.

Moved here from hub wiring so the LR1120/LR1110 bootloader IDs live in one place (next to the LR1121 ones they are compared against) and the mapping is host-testable without a hub.

Definition at line 70 of file lr1121_firmware_decisions.h.

lr1121_chip_family_for_device_type()

const char * esphome::home_io_control::lr1121_chip_family_for_device_type ( uint8_t device_type )

nodiscardconstexpr

Human-readable chip family for a normal-mode device_type that is not the LR1121 value above, for an actionable REJECT_WRONG_CHIP message (the layer-3 counterpart of lr1121_chip_family_for_bootloader() above).

Definition at line 81 of file lr1121_firmware_decisions.h.

lr1121_firmware_is_outdated()

bool esphome::home_io_control::lr1121_firmware_is_outdated ( uint8_t fw_major, uint8_t fw_minor )

nodiscardconstexpr

Pure comparison against the known-latest constants above — no I/O, host-testable.

Only ever flags a version as outdated when it is strictly older than what this file knows about; versions equal to or newer than LR1121_KNOWN_LATEST_FW_* (including any real future firmware this snapshot predates) are never flagged, so a stale baked-in constant fails silent rather than crying wolf.

Definition at line 135 of file radio_lr1121.h.

lr1121_flash_decision()

FlashDecision esphome::home_io_control::lr1121_flash_decision ( uint8_t device_type, uint8_t bootloader_chip_type, uint16_t bootloader_version, uint16_t installed_fw, uint16_t target_fw, bool already_confirmed )

nodiscardconstexpr

The single decision point for whether/how to flash target_fw.

Order of checks. Layers 3 and 4 below are the two chip-identity checks (normal-mode device_type and bootloader-mode version); everything else exists to make sure an absent read is never mistaken for evidence:

1. Boot excursion never completed at all (bootloader_version unknown) – nothing below can be evaluated, so this is checked first and short-circuits straight to NEEDS_CONFIRMATION.
2. Layer 4 – bootloader-mode identity: type must be the production-silicon byte AND the bootloader version must be one an LR1121 actually reports (as opposed to an LR1120 or LR1110, which also answer bootloader-mode GetVersion, just with different values).
3. Normal-mode read never happened (device_type unknown, e.g. after a failed init()) – unknown is not evidence of the wrong chip, so this is checked before layer 3 can turn it into a false REJECT_WRONG_CHIP.
4. Layer 3 – normal-mode chip identity: distinguishes LR1121 from LR1110/LR1120 while normal-mode firmware can still answer.
5. Bootloader/target compatibility (the three-way rule – known-compatible proceeds, known-incompatible refuses, unknown-target asks for confirmation rather than refusing so a future firmware release keeps working without a code change here).
6. Only once the pairing is positively known-good: the not-newer-so-confirm version compare.

Every input below has its own "unknown" sentinel, and every one of them routes to NEEDS_CONFIRMATION rather than a rejection or a false PROCEED – an absent read is never evidence of anything, safe or unsafe:

• bootloader_version == 0: the boot-time excursion never successfully read one. 0x0000 is not a value any real LR11xx bootloader reports.
• device_type == 0: the normal-mode read never happened at all (failed init(), or the read itself failed). Deliberately still allowed to reach a flash after confirmation – a radio that failed to initialize is exactly the case reflashing is meant to recover.
• target_fw == 0: the build could not derive a version from the filename and none was configured; can never match a LR1121_KNOWN_BOOTLOADER_REQUIREMENTS entry (none uses 0), so it always resolves to BootloaderSupport::UNKNOWN_TARGET.
• installed_fw == 0: the installed version is unknown (device_type known-good but the firmware-version bytes could not be read) – treated exactly like "not newer", never as "older than everything" the way a naive target_fw > installed_fw would.

Parameters

device_type	Chip identity byte from a normal-mode GetVersion (layer 3); 0 if that read never happened.
bootloader_chip_type	type byte from the bootloader-mode GetVersion read at boot (layer 4); 0xDF (LR1121_BOOTLOADER_TYPE_FOR_FIRMWARE_DECISIONS) for production silicon of any LR11xx family, or 0 if the boot excursion never completed.
bootloader_version	Bootloader version read at boot; one of LR1121_BOOTLOADER_2100/2101 for a genuine LR1121, or 0 if never successfully read.
installed_fw	Currently-installed transceiver firmware version (0 if unknown, e.g. after a failed init()).
target_fw	Configured target firmware version (0 if unknown — see above).
already_confirmed	True on a second button press within the confirmation window; allows every non-hard-reject outcome to proceed instead of asking again.

Returns

The decision; see FlashDecision.

Definition at line 291 of file lr1121_firmware_decisions.h.

Here is the call graph for this function:

lr1121_required_bootloader_for()

uint16_t esphome::home_io_control::lr1121_required_bootloader_for ( uint16_t target_fw )

nodiscardconstexpr

Required bootloader for a known target firmware version.

Returns

The paired bootloader from LR1121_KNOWN_BOOTLOADER_REQUIREMENTS, or 0 when target_fw is not in the table – an "unverified", not "incompatible", target (see that table's comment), and never a real requirement value since no table entry uses 0.

Definition at line 138 of file lr1121_firmware_decisions.h.

make_management_result()

ManagementActionResult esphome::home_io_control::make_management_result ( const std::string & action, const std::string & device_id )

static

Definition at line 339 of file management_actions.cpp.

manufacturer_name()

const char * esphome::home_io_control::manufacturer_name

(

uint8_t

id

)

Get a human-readable manufacturer name from the protocol manufacturer byte.

The manufacturer ID is a 1-based index assigned by the IO-Homecontrol alliance. IDs outside the known range return "unknown". When an unknown ID appears at runtime, the pairing flow logs a warning suggesting the user file a GitHub issue.

Warning

Display-only — do not use this for YAML. Four of the twelve names do not round-trip through .strip().lower() to their manufacturer: YAML token (MANUFACTURER_OPTIONS, __init__.py): "Hörmann" has an umlaut the YAML token (hormann) drops, and "ASSA ABLOY"/"WINDOW MASTER"/"Atlantic Group" use a space where the YAML token uses _. There is currently no YAML-token accessor for manufacturers — see yaml_device_type_name() (proto_device_model.h) for the pattern this would follow if one is ever added.

Parameters

id	Manufacturer ID byte (1–12 for known manufacturers).

Returns

Null-terminated lowercase string such as "unknown", or mixed-case name like "Somfy".

Definition at line 117 of file proto_constants.cpp.

match_heating_named_value()

bool esphome::home_io_control::match_heating_named_value ( const std::string & token, const HeatingNamedValue * table, size_t table_len, float & out )

static

Match token against table; on a hit set out and return true.

Definition at line 413 of file management_actions.cpp.

node_id_to_string()

std::string esphome::home_io_control::node_id_to_string

(

const uint8_t

id[NODE_ID_SIZE]

)

Format a 3‑byte node ID as a 6‑character uppercase hex string.

Parameters

id	3‑byte node ID.

Returns

Hex string (e.g., "123ABC").

Definition at line 50 of file proto_frame.cpp.

normalize_device_id_argument()

std::string esphome::home_io_control::normalize_device_id_argument ( const std::string & device_id )

static

Definition at line 321 of file management_actions.cpp.

Here is the call graph for this function:

normalize_lower_argument()

std::string esphome::home_io_control::normalize_lower_argument ( const std::string & value )

static

Lowercase + ASCII-trim a native-API string argument.

Definition at line 399 of file management_actions.cpp.

Here is the call graph for this function:

oneway_intent_to_target()

std::optional< float > esphome::home_io_control::oneway_intent_to_target	(	uint8_t	main0,
		uint8_t	main1 )

Resolve a 1W main-byte pair to an optimistic IO target position, if unambiguous.

Shares decode_1w_main_intent()'s special-code checks so the two never disagree. Returns empty for POS_STOP (the caller must clear any optimistic target instead — stop is not a target) and for codes with no settled position (FAVORITE/VENT/FORCE_OPEN/SECURED_TARGET/ DEFAULT/UNKNOWN) — those cases still get a confirmation poll, just no optimistic claim.

Parameters

main0	First main byte (position or special code).
main1	Second main byte (modifier); unused by every branch that resolves a target.

Returns

IO target position (0=open, 100=closed) if resolvable; empty otherwise.

Definition at line 311 of file proto_codecs.cpp.

originator_name()

const char * esphome::home_io_control::originator_name

(

uint8_t

originator

)

Get a human-readable name for a command originator byte.

Parameters

originator

Originator code from the first data byte of CMD_EXECUTE.

Returns

Null-terminated string such as "rain_sensor" or "user_remote".

Definition at line 174 of file proto_constants.cpp.

pairing_stage_name()

const char * esphome::home_io_control::pairing_stage_name ( pairing::PairingState state )

inline

Get a short, log/telemetry-friendly name for a pairing state.

Parameters

state

Pairing state.

Returns

Null-terminated lowercase string such as "wait_key_challenge".

Definition at line 77 of file hub_pairing.h.

parse()

bool esphome::home_io_control::parse	(	const uint8_t *	buf,
		uint8_t	buf_len,
		IoFrame &	f )

Parse a wire buffer into a parsed IoFrame (validates length and CTRL0).

Parameters

buf	Raw byte buffer.
buf_len	Number of bytes in buf. Accepted shapes: exactly the CTRL0-declared length (has_mac comes out false), or — only for a command where frame_carries_mac_trailer() is true — that length plus HMAC_SIZE (the trailing bytes are copied into f.mac and has_mac comes out true). Any other length, or that same wider length for a command that doesn't carry a trailer, is rejected. data_len is always buf_len's declared portion minus FRAME_MIN_SIZE — the trailer is never data.
f	Output parsed frame.

Returns

true if parse succeeded; false otherwise.

Definition at line 154 of file proto_frame.cpp.

Here is the call graph for this function:

parse_heating_arguments()

bool esphome::home_io_control::parse_heating_arguments ( const std::string & function, const std::string & value, HeatingFunction & fn_out, float & value_out, std::string & error )

static

Parse the (function, value) argument pair of the heating_control action.

Every native-API argument is a string (ManagementServiceDescriptor hardcodes SERVICE_ARG_TYPE_STRING), so this turns the two strings into a HeatingFunction plus the float encode_heating_payload() expects: degrees C for set_temperature, a HeatingMode value for set_mode, 0/1 for set_presence / set_window, and an ignored 0 for power_on / midnight_sync. On any malformed input it fills error with a caller-facing message and returns false rather than coercing a value. Kept next to the action (not in proto_heating) because the climate entity receives typed enums from Home Assistant and needs no string parsing.

Parameters

function	Function name argument.
value	Value argument.
fn_out	Parsed function on success.
value_out	Parsed value on success (0 for the value-less functions).
error	Caller-facing message on failure.

Returns

true on a fully valid pair.

Definition at line 461 of file management_actions.cpp.

Here is the call graph for this function:

parse_heating_temperature()

bool esphome::home_io_control::parse_heating_temperature ( const std::string & value, float & value_out, std::string & error )

static

Parse set_temperature's value into degrees Celsius, range-checked.

Definition at line 425 of file management_actions.cpp.

Here is the call graph for this function:

parse_probe_index()

bool esphome::home_io_control::parse_probe_index ( const std::string & text, uint8_t & out )

static

Parse a probe_device()/probe_sweep() index argument into a byte.

Accepts both a bare decimal string ("6") and a "0x"-prefixed hex string ("0x06") — the two shapes a Home Assistant user is likely to type when copying a value out of a captured frame dump. Rejects anything else (empty string, trailing garbage, out-of-range value) rather than silently defaulting to 0, since a wrong index silently sent as 0 would misrepresent what was actually probed.

Parameters

text	Argument as received from the native API call.
out	Parsed byte on success; left untouched on failure.

Returns

true if text is exactly one well-formed byte value.

Definition at line 376 of file management_actions.cpp.

power_save_mode_name()

const char * esphome::home_io_control::power_save_mode_name

(

uint8_t

mode

)

Get a human-readable power save mode name.

Parameters

mode	Power save value (0–1) extracted from the Multi Information Byte.

Returns

Null-terminated string such as "always_alive" or "low_power".

Definition at line 163 of file proto_constants.cpp.

recover_system_key_from_transfer()

bool esphome::home_io_control::recover_system_key_from_transfer	(	const uint8_t	transfer_payload[AES_KEY_SIZE],
		const uint8_t	challenge[HMAC_SIZE],
		uint8_t	out_key[AES_KEY_SIZE] )

Recover the system key from a CMD_KEY_TRANSFER payload.

Recover the system key from an inbound CMD_KEY_TRANSFER (0x32) payload — the decode counterpart to create_key_transfer()'s encode.

See proto_commands.h for the full contract; this is the single place the IV-data convention ({CMD_KEY_INIT}, len 1) lives for the decode direction, mirroring create_key_transfer()'s encode side below.

Centralizes the IV-data convention in one place: create_key_transfer() derives its IV from the preceding CMD_KEY_INIT (0x31) command byte only (see its own doxygen), so decoding must use that same single-byte {CMD_KEY_INIT} — not the 0x32 frame's own command byte, and not the discovery frame. crypt_key() is symmetric, so this is the same primitive in reverse.

Parameters

transfer_payload	16-byte CMD_KEY_TRANSFER payload (frame.data).
challenge	The 6-byte challenge we generated and sent in our own CMD_CHALLENGE_REQ (0x3C) — the far side mixes this into its IV, so decoding requires the exact same bytes.
out_key	Output: recovered 16-byte system key.

Returns

true on success (crypt_key() AES failure is the only false case).

Definition at line 720 of file proto_commands.cpp.

Here is the call graph for this function:

render_frame_hex_redacted()

void esphome::home_io_control::render_frame_hex_redacted ( const uint8_t * data, uint8_t len, char * out, size_t out_size )

inline

Render a frame's bytes as spaced hex text, masking the payload when the command carries key material (see command_carries_key_material()).

Kept outside the IOHOME_FRAME_LOG guard so the redaction behavior is unit-testable independent of the firmware-only logging build flag.

Warning

IOHOME_UNSAFE_LOG_KEY_MATERIAL disables the masking below entirely. It exists solely so a maintainer can capture a genuine pairing exchange for tests/corpus/ (see tests/corpus/README.md's key-hygiene section) when the normal ingest.py --rekey flow has no other way to obtain the raw bytes. Never set it outside a deliberate, local, own-hardware capture session: build with it, capture the one exchange you need, --rekey immediately, then rebuild without it. Never commit a config with it enabled, never use it on a device whose logs anyone else can see, and never paste output captured under it into an issue/chat before re-keying. hub_core.cpp's setup() logs a loud warning every boot while this is defined specifically so an accidentally-left-on build can't stay quiet.

Parameters

data	Raw serialized frame bytes (header + payload, no CRC).
len	Total length of data.
out	Buffer to write the rendered text into.
out_size	Size of out.

Definition at line 71 of file log_frame.h.

Here is the call graph for this function:

resolve_discovery_destination()

const uint8_t * esphome::home_io_control::resolve_discovery_destination	(	uint8_t	command,
		bool	destination_auto,
		const uint8_t	destination[NODE_ID_SIZE] )

Resolve the destination address for a discovery command.

When destination_auto is true, returns the conventional address for the given command code. Otherwise returns the configured destination value.

Parameters

command	Discovery command code.
destination_auto	Whether to use the automatic mapping.
destination	Explicit 3-byte destination when auto is false.

Returns

Pointer to the resolved 3-byte node ID.

Definition at line 191 of file tuning_config.cpp.

resolve_oneway_wire_profile()

OneWayWireProfile esphome::home_io_control::resolve_oneway_wire_profile ( uint8_t manufacturer )

inline

Resolve an identity's 1W wire profile from its manufacturer byte.

Pure. Somfy (0x02) and unset (0x00) both map to the historical Somfy-shaped default (ONEWAY_EXECUTE_ACEI, EnrollGesture::SOMFY); only VELUX (0x01) is special so far (ONEWAY_EXECUTE_ACEI_VELUX, EnrollGesture::VELUX_KLI, the class sweep). Any other explicitly-set manufacturer returns the Somfy default with profile_is_a_guess=true so the Python schema can warn (__init__.py _validate_oneway_controllers() — keep the {somfy, velux} set here in sync with the warning there; there is no automated check).

Parameters

manufacturer

The identity's manufacturer byte (MANUFACTURER_*, or a raw value).

Definition at line 114 of file oneway_controller.h.

rssi_scaled_to_dbm()

int16_t esphome::home_io_control::rssi_scaled_to_dbm ( int16_t scaled )

inline

Convert an rssi_ema_scaled fixed-point value to whole dBm (round half away from zero).

Parameters

scaled

Fixed-point EMA value in 1/RSSI_EMA_SCALE dBm units (not the sentinel).

Returns

Rounded dBm value.

Definition at line 367 of file proto_device_model.h.

serialize()

uint8_t esphome::home_io_control::serialize	(	const IoFrame &	f,
		uint8_t *	buf,
		uint8_t	buf_size )

Serialize a parsed frame into a wire buffer (without CRC).

Parameters

f	Parsed frame. When f.has_mac, the 6-byte mac trailer is appended after the declared payload and counted in the returned length, so a caller's CRC (computed over the returned length) covers it.
buf	Output buffer (must be at least frame_length(f) bytes, or +HMAC_SIZE when f.has_mac).
buf_size	Size of buf.

Returns

Number of bytes written (declared length, plus HMAC_SIZE when f.has_mac), or 0 on failure.

Definition at line 114 of file proto_frame.cpp.

Here is the call graph for this function:

set_cmd()

bool esphome::home_io_control::set_cmd	(	IoFrame &	f,
		uint8_t	cmd,
		const uint8_t *	params = nullptr,
		uint8_t	params_len = 0 )

Set command and payload.

Parameters

f	Frame to modify.
cmd	Command ID.
params	Pointer to payload bytes (may be nullptr for zero‑length).
params_len	Payload length (0–23).

Returns

true if frame fits within size limits; false otherwise.

Definition at line 85 of file proto_frame.cpp.

set_dst()

void esphome::home_io_control::set_dst	(	IoFrame &	f,
		const uint8_t	id[NODE_ID_SIZE] )

Set destination node ID.

Parameters

f	Frame to modify.
id	3‑byte destination address.

Definition at line 82 of file proto_frame.cpp.

set_src()

void esphome::home_io_control::set_src	(	IoFrame &	f,
		const uint8_t	id[NODE_ID_SIZE] )

Set source node ID.

Parameters

f	Frame to modify.
id	3‑byte source address.

Definition at line 83 of file proto_frame.cpp.

settle_delay_ms()

uint32_t esphome::home_io_control::settle_delay_ms ( uint32_t interval_ms, uint32_t hint_delay_ms, bool cap_for_stop )

inlinenodiscard

Resolve the follow-up settle-poll delay while a device may still be moving.

This is the single source of truth for the motion-tracking cadence. The delay is the configured interval_ms, or DEFAULT_SETTLE_POLL_DELAY_MS when no interval is configured (interval_ms == 0). A device-provided byte-7 hint (hint_delay_ms, 0 when absent) and a STOP command (cap_for_stop) may only shorten the delay, never lengthen it.

Note: this resolves the settle delay only — it is intentionally independent of whether a device keeps polling after coming to rest. Periodic monitoring after rest remains opt-in and is gated on interval_ms != 0 by the command paths, so defaulting the settle delay here does not turn every device into a periodic poller.

Returns

Settle delay in milliseconds (always non-zero).

Definition at line 77 of file status_poll_policy.h.

soft_phy_air_time_us()

uint32_t esphome::home_io_control::soft_phy_air_time_us ( uint32_t raw_bytes )

constexpr

On-air time in microseconds for raw_bytes bytes at the protocol's line rate.

One byte is 8 / 38400 s = 208.333 µs. Computed as an integer division rounded up, so the result never falls short of a whole byte's air time and a caller that waits on it never reads the chip's buffer early. The numerator peaks around 360 million for the longest frame this is ever asked about, well inside uint32_t.

Definition at line 95 of file radio_soft_phy_driver_base.h.

soft_phy_peek_frame_length()

uint8_t esphome::home_io_control::soft_phy_peek_frame_length	(	const uint8_t *	raw,
		uint8_t	raw_len )

Recover a frame's total length from the very first UART cell of a reception.

CTRL0 bits [4:0] hold frame_length - 1 (see proto_frame.h), and CTRL0 is the first byte after the sync word — so ten bits of air time are enough to learn how long the whole frame will be. Alignment is not yet known at that point, so every probe offset is tried and the largest plausible answer wins: over-waiting by a few bytes costs a little latency, whereas under-waiting would truncate the frame.

Parameters

raw	Raw bytes read from the chip's data buffer, starting at the reception's own offset.
raw_len	Number of raw bytes available (three is enough at any alignment).

Returns

Plausible frame length in bytes, or 0 when no offset yields one.

Definition at line 228 of file radio_soft_phy.cpp.

Here is the call graph for this function:

soft_phy_raw_bytes_for_frame()

uint8_t esphome::home_io_control::soft_phy_raw_bytes_for_frame

(

uint8_t

frame_len

)

Raw on-air bytes needed to carry a whole frame: frame_len protocol bytes plus the two trailing CRC bytes, each UART-packed into a 10-bit cell.

This is what makes a length-driven receive possible at all: a frame's own size is knowable from its first decoded byte, so the raw byte count it will occupy is knowable too — no chip needs to tell us where the frame ends.

Parameters

frame_len

Protocol frame length in bytes (CTRL0's own length field, +1).

Returns

Raw byte count, rounded up to whole bytes.

Definition at line 220 of file radio_soft_phy.cpp.

stored_node_id_is_valid()

bool esphome::home_io_control::stored_node_id_is_valid ( const uint8_t id[NODE_ID_SIZE] )

inline

Check if a stored node ID is valid (not all-zero, not all-0xFF).

Parameters

id	3‑byte node ID buffer.

Returns

true if the ID is non-zero and non-0xFF.

Definition at line 1144 of file hub_core.h.

sx1262_bandwidth_from_string()

std::optional< SX1262RxBandwidth > esphome::home_io_control::sx1262_bandwidth_from_string

(

const std::string &

value

)

Convert a YAML bandwidth string to the enum value.

Parameters

value

YAML string such as "117.3kHz" or "156.2kHz".

Returns

Bandwidth enum, or std::nullopt on invalid input.

Definition at line 122 of file tuning_config.cpp.

Here is the call graph for this function:

sx1262_bandwidth_table()

BandwidthTableView esphome::home_io_control::sx1262_bandwidth_table

(

)

The SX1262 RX-bandwidth option table.

Exposed so tests derive their legal-option lists from the same source production uses rather than re-listing them by hand.

Definition at line 109 of file tuning_config.cpp.

sx1262_bandwidth_to_khz()

float esphome::home_io_control::sx1262_bandwidth_to_khz

(

SX1262RxBandwidth

bw

)

Convert a bandwidth enum to the numeric kHz value used in YAML/logs.

Parameters

bw	SX1262 bandwidth enum.

Returns

Floating-point kHz value (39.0, 46.9, 58.6, 78.2, 117.3, 156.2, or 187.2).

Definition at line 113 of file tuning_config.cpp.

Here is the call graph for this function:

sx1262_bandwidth_to_string()

std::string esphome::home_io_control::sx1262_bandwidth_to_string

(

SX1262RxBandwidth

bw

)

Format a bandwidth enum as its YAML/UI option string (bare kHz number, e.g.

"117.3").

Parameters

bw	SX1262 bandwidth enum.

Returns

Bandwidth rendered with one decimal place and a "kHz" suffix.

Definition at line 118 of file tuning_config.cpp.

Here is the call graph for this function:

sx1276_bandwidth_from_string()

std::optional< SX1276RxBandwidth > esphome::home_io_control::sx1276_bandwidth_from_string

(

const std::string &

value

)

Convert a YAML SX1276 bandwidth string to the enum value.

Parameters

value

YAML string such as "41.7" or "83.3kHz".

Returns

Bandwidth enum, or std::nullopt on invalid input.

Definition at line 137 of file tuning_config.cpp.

Here is the call graph for this function:

sx1276_bandwidth_table()

BandwidthTableView esphome::home_io_control::sx1276_bandwidth_table

(

)

The SX1276 RX-bandwidth option table (see sx1262_bandwidth_table()).

Definition at line 110 of file tuning_config.cpp.

sx1276_bandwidth_to_khz()

float esphome::home_io_control::sx1276_bandwidth_to_khz

(

SX1276RxBandwidth

bw

)

Convert an SX1276 bandwidth enum to the numeric kHz value used in YAML/logs.

Parameters

bw	SX1276 bandwidth enum.

Returns

Floating-point kHz value (20.8, 41.7, 62.5, 83.3, or 125.0).

Definition at line 128 of file tuning_config.cpp.

Here is the call graph for this function:

sx1276_bandwidth_to_string()

std::string esphome::home_io_control::sx1276_bandwidth_to_string

(

SX1276RxBandwidth

bw

)

Format an SX1276 bandwidth enum as its YAML/UI option string (bare kHz number).

Parameters

bw	SX1276 bandwidth enum.

Returns

Bandwidth rendered with one decimal place (e.g. "41.7").

Definition at line 133 of file tuning_config.cpp.

Here is the call graph for this function:

trim_ascii_whitespace()

std::string esphome::home_io_control::trim_ascii_whitespace

(

const std::string &

value

)

Trim leading and trailing ASCII whitespace from a string.

This is shared by device-name validation and management actions so both paths normalize input consistently before comparing or writing device metadata.

Parameters

value

Input string.

Returns

Copy of the string with leading and trailing ASCII whitespace removed.

Definition at line 76 of file proto_codecs.cpp.

tuning_config_full_snapshot()

std::string esphome::home_io_control::tuning_config_full_snapshot

(

const TuningConfig &

cfg

)

Format the current tuning configuration as a full one-line snapshot.

Emits every non-default value, regardless of whether it was changed from YAML or from the HA UI. This is logged at the start of every pairing attempt.

Parameters

cfg	Current tuning configuration.

Returns

One-line snapshot string, or a "defaults" marker when nothing is overridden.

Definition at line 277 of file tuning_config.cpp.

Here is the call graph for this function:

tuning_config_snapshot()

std::string esphome::home_io_control::tuning_config_snapshot

(

const TuningConfig &

cfg

)

Format the current tuning configuration as a one-line YAML-compatible snapshot.

Only values that differ from the default are emitted, so the line can be copied back into YAML with minimal editing. When all values are default, an empty string is returned.

Parameters

cfg	Current tuning configuration.

Returns

One-line snapshot string, or empty when no overrides are active.

Definition at line 228 of file tuning_config.cpp.

Here is the call graph for this function:

tuning_number_params_begin()

const TuningNumberParam * esphome::home_io_control::tuning_number_params_begin

(

)

Definition at line 201 of file tuning_registry.cpp.

tuning_number_params_end()

const TuningNumberParam * esphome::home_io_control::tuning_number_params_end

(

)

Definition at line 202 of file tuning_registry.cpp.

tuning_select_params_begin()

const TuningSelectParam * esphome::home_io_control::tuning_select_params_begin

(

)

Definition at line 203 of file tuning_registry.cpp.

tuning_select_params_end()

const TuningSelectParam * esphome::home_io_control::tuning_select_params_end

(

)

Definition at line 204 of file tuning_registry.cpp.

tuning_update_log_line()

std::string esphome::home_io_control::tuning_update_log_line	(	const std::string &	name,
		const std::string &	value )

Format a single tuning update for the log.

Parameters

name	YAML key name of the updated parameter.
value	YAML-compatible string representation of the new value.

Returns

One-line log string suitable for ESP_LOGI.

Definition at line 224 of file tuning_config.cpp.

uart_encode_packet()

uint8_t esphome::home_io_control::uart_encode_packet	(	const uint8_t *	data,
		uint8_t	len,
		uint8_t *	encoded,
		uint8_t	encoded_max_len )

UART-encode a buffer of bytes (start bit 0, 8 data bits LSB-first, stop bit 1).

Returns

Number of encoded bytes, or 0 if the output buffer is too small.

Definition at line 244 of file radio_soft_phy.cpp.

yaml_device_type_name()

const char * esphome::home_io_control::yaml_device_type_name

(

DeviceType

type

)

Return the YAML-friendly device-type name for types exposed in the Python schema.

Parameters

type	Device type enum.

Returns

Null‑terminated string (e.g., "external_venetian_blind"), or nullptr if the type has no symbolic YAML alias (user must use a raw numeric value).

Definition at line 170 of file proto_device_model.cpp.

Variable Documentation

ACEI_EXTENDED_MASK

uint8_t esphome::home_io_control::ACEI_EXTENDED_MASK = 0x06

staticconstexpr

Bits [2:1]: extended field.

Definition at line 504 of file proto_constants.h.

ACEI_EXTENDED_SHIFT

uint8_t esphome::home_io_control::ACEI_EXTENDED_SHIFT = 1

staticconstexpr

Shift for extended field extraction.

Definition at line 505 of file proto_constants.h.

ACEI_LEVEL_AUTO_DEFAULT

uint8_t esphome::home_io_control::ACEI_LEVEL_AUTO_DEFAULT = 7

staticconstexpr

Default automatic level (lowest).

Definition at line 523 of file proto_constants.h.

ACEI_LEVEL_AUTO_SAAC

uint8_t esphome::home_io_control::ACEI_LEVEL_AUTO_SAAC = 6

staticconstexpr

Stand-alone automatic controller.

Definition at line 522 of file proto_constants.h.

ACEI_LEVEL_COMFORT_1

uint8_t esphome::home_io_control::ACEI_LEVEL_COMFORT_1 = 4

staticconstexpr

Comfort automation level 1.

Definition at line 520 of file proto_constants.h.

ACEI_LEVEL_COMFORT_2

uint8_t esphome::home_io_control::ACEI_LEVEL_COMFORT_2 = 5

staticconstexpr

Comfort automation level 2.

Definition at line 521 of file proto_constants.h.

ACEI_LEVEL_MASK

uint8_t esphome::home_io_control::ACEI_LEVEL_MASK = 0xE0

staticconstexpr

Bits [7:5]: priority level (0–7).

Definition at line 508 of file proto_constants.h.

ACEI_LEVEL_PROTECTION_HUMAN

uint8_t esphome::home_io_control::ACEI_LEVEL_PROTECTION_HUMAN = 0

staticconstexpr

ACEI priority level values (0–7).

These values are extracted from the ACEI byte via (acei & ACEI_LEVEL_MASK) >> ACEI_LEVEL_SHIFT. Personal safety (highest, overrides all).

Definition at line 516 of file proto_constants.h.

ACEI_LEVEL_PROTECTION_SENSOR

uint8_t esphome::home_io_control::ACEI_LEVEL_PROTECTION_SENSOR = 1

staticconstexpr

Goods/environment protection via sensors.

Definition at line 517 of file proto_constants.h.

ACEI_LEVEL_SHIFT

uint8_t esphome::home_io_control::ACEI_LEVEL_SHIFT = 5

staticconstexpr

Shift for priority level extraction.

Definition at line 509 of file proto_constants.h.

ACEI_LEVEL_USER_DEFAULT

uint8_t esphome::home_io_control::ACEI_LEVEL_USER_DEFAULT = 3

staticconstexpr

Default remote controller priority.

Definition at line 519 of file proto_constants.h.

ACEI_LEVEL_USER_HIGH

uint8_t esphome::home_io_control::ACEI_LEVEL_USER_HIGH = 2

staticconstexpr

High-priority user controller.

Definition at line 518 of file proto_constants.h.

ACEI_SERVICE_MASK

uint8_t esphome::home_io_control::ACEI_SERVICE_MASK = 0x18

staticconstexpr

Bits [4:3]: service type.

Definition at line 506 of file proto_constants.h.

ACEI_SERVICE_SHIFT

uint8_t esphome::home_io_control::ACEI_SERVICE_SHIFT = 3

staticconstexpr

Shift for service field extraction.

Definition at line 507 of file proto_constants.h.

ACEI_VALID_BIT

uint8_t esphome::home_io_control::ACEI_VALID_BIT = 0x01

staticconstexpr

ACEI byte bit-field definitions.

The ACEI byte is the second byte of the CMD_EXECUTE payload. It encodes the priority level and service class of the command, controlling which commands can override others. Devices reject commands with lower priority than their current locked level (resulting in RESULT_PRIORITY_LEVEL_LOCKED). Bit 0: command validity flag.

Definition at line 503 of file proto_constants.h.

ADDRESS_SUFFIX_BROADCAST

uint8_t esphome::home_io_control::ADDRESS_SUFFIX_BROADCAST = 0x3F

staticconstexpr

Suffix for "all devices of this type" broadcast.

Definition at line 86 of file proto_codecs.h.

ADDRESS_SUFFIX_DISCOVERY

uint8_t esphome::home_io_control::ADDRESS_SUFFIX_DISCOVERY = 0x3B

staticconstexpr

Suffix for discovery-related broadcasts.

Definition at line 87 of file proto_codecs.h.

ADDRESS_SUFFIX_MASK

uint8_t esphome::home_io_control::ADDRESS_SUFFIX_MASK = 0x3F

staticconstexpr

Well-known address suffix values in the broadcast address space.

When the first byte of a 3-byte IO-Homecontrol address is 0x00, the low 6 bits of the third byte carry a suffix that identifies the broadcast category. Mask to extract the 6-bit suffix from addr[2].

Definition at line 85 of file proto_codecs.h.

AES_BLOCK_SIZE

uint8_t esphome::home_io_control::AES_BLOCK_SIZE = 16

staticconstexpr

AES block size.

Definition at line 24 of file proto_sizes.h.

AES_KEY_SIZE

uint8_t esphome::home_io_control::AES_KEY_SIZE = 16

staticconstexpr

AES-128 key size.

Definition at line 23 of file proto_sizes.h.

ATT_CLASS_10S

uint8_t esphome::home_io_control::ATT_CLASS_10S = 1

staticconstexpr

Response within 10 seconds.

Definition at line 603 of file proto_constants.h.

ATT_CLASS_20S

uint8_t esphome::home_io_control::ATT_CLASS_20S = 2

staticconstexpr

Response within 20 seconds.

Definition at line 604 of file proto_constants.h.

ATT_CLASS_40S

uint8_t esphome::home_io_control::ATT_CLASS_40S = 3

staticconstexpr

Response within 40 seconds.

Definition at line 605 of file proto_constants.h.

ATT_CLASS_5S

uint8_t esphome::home_io_control::ATT_CLASS_5S = 0

staticconstexpr

Actuator Turnaround Time (ATT) class values.

Indicates the maximum time window in which the actuator normally responds after receiving a command. Extracted from the Multi Information Byte via (flags & DISCOVERY_FLAGS_ATT_MASK) >> DISCOVERY_FLAGS_ATT_SHIFT. Response within 5 seconds.

Definition at line 602 of file proto_constants.h.

BINARY_ENTITY_OFF_POSITION

uint8_t esphome::home_io_control::BINARY_ENTITY_OFF_POSITION = 100

staticconstexpr

Position value written for binary OFF commands (light off, switch off, lock lock).

Definition at line 24 of file operation_queue.h.

BINARY_ENTITY_ON_POSITION

uint8_t esphome::home_io_control::BINARY_ENTITY_ON_POSITION = 0

staticconstexpr

Position value written for binary ON commands (light on, switch on, lock unlock).

Definition at line 22 of file operation_queue.h.

BITS_PER_BYTE

uint8_t esphome::home_io_control::BITS_PER_BYTE = 8

staticconstexpr

Number of bits in one protocol byte.

Definition at line 27 of file proto_sizes.h.

BROADCAST_DISCOVER

uint8_t esphome::home_io_control::BROADCAST_DISCOVER[NODE_ID_SIZE] = {0x00, 0x00, 0x3B}

staticconstexpr

Broadcast address for device discovery (0x00003B).

Used as destination in CMD_DISCOVER_REQ frames to trigger all pairable devices to respond.

Definition at line 388 of file proto_constants.h.

BROADCAST_DISCOVER_ALT

uint8_t esphome::home_io_control::BROADCAST_DISCOVER_ALT[NODE_ID_SIZE] = {0x00, 0x00, 0x3F}

staticconstexpr

Alternate discovery / 1W broadcast address (0x00003F).

Used as destination for CMD_DISCOVER_ALT_REQ (0x2E) alternate discovery, and the address on which devices in 1W-triggered pairing mode listen. Distinct from the 2W discovery broadcast BROADCAST_DISCOVER (0x00003B).

Definition at line 394 of file proto_constants.h.

CMD_ACTIVATE_MODE

uint8_t esphome::home_io_control::CMD_ACTIVATE_MODE = 0x01

staticconstexpr

Activate device mode (scene, ventilation) — requires auth.

Definition at line 25 of file proto_constants.h.

CMD_ADDRESS_REQ

uint8_t esphome::home_io_control::CMD_ADDRESS_REQ

staticconstexpr

Initial value:

                                     =
0x36

"Report your address" request.

Not pairing-specific: it's captured both closing a Velux KLR200 pairing (tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml) and, on a completely different hub, sent to an already-paired device with no pairing in progress at all (a Velux KIG300 probing a Somfy dimmer in tests/corpus/captures/probe/velux_kig300_probe_capability_burst.yaml). Answered by the key-extraction responder's create_address_resp_device_role() (handle_address_req_() in key_extraction_responder.cpp).

Definition at line 133 of file proto_constants.h.

CMD_ADDRESS_RESP

uint8_t esphome::home_io_control::CMD_ADDRESS_RESP

staticconstexpr

Initial value:

                                      =
0x37

Address assignment response: the device returns its own 3-byte backbone address, byte-identical to the one it reported at data[2..4] (DISCOVERY_RESP_BACKBONE_OFFSET) of its CMD_DISCOVER_RESP earlier in the same session — an independent confirmation of that offset.

The only capture of this command in the corpus is still tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml, where a Velux KLR200 closes pairing with 0x36 and then challenges the 0x37 it gets back (see CMD_CHALLENGE_REQ) — sent by create_address_resp_device_role() (proto_commands.h/.cpp), the key-extraction responder's answer to CMD_ADDRESS_REQ.

Definition at line 141 of file proto_constants.h.

CMD_CHALLENGE_REQ

uint8_t esphome::home_io_control::CMD_CHALLENGE_REQ

staticconstexpr

Initial value:

                                       =
0x3C

6-byte random challenge.

Usually a device challenging a controller's command, but the protocol is symmetric and controllers challenge devices too: in tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml a KLR200 issues 0x3C against the device's own CMD_ADDRESS_RESP. The key-extraction responder now answers exactly that inbound direction (KeyExtractionResponder::handle_address_challenge_() in key_extraction_responder.cpp), so both directions are implemented, not just the outbound one.

Definition at line 159 of file proto_constants.h.

CMD_CHALLENGE_RESP

uint8_t esphome::home_io_control::CMD_CHALLENGE_RESP

staticconstexpr

Initial value:

                                        =
0x3D

HMAC proof answering a 0x3C.

Whoever is challenged authenticates its own preceding frame: the transcript is [cmd, data...] of the challenged party's last frame (create_challenge_resp()), never the challenger's. That holds in both directions — the device-side 0x3D in velux_kux100_pairing_full.yaml (over its own 0x37) was recomputed under that installation's recovered key and confirmed before the capture was re-keyed, so it is measured, not assumed by symmetry.

Definition at line 167 of file proto_constants.h.

CMD_DISCOVER_ALT_REQ

uint8_t esphome::home_io_control::CMD_DISCOVER_ALT_REQ

staticconstexpr

Initial value:

                                          =
0x2E

Alternate discovery.

Broadcast (to 0x00003F) draws no response at all on every device this project has real evidence for — a Somfy Izymo dimmer (tests/corpus/captures/discovery/somfy_izymo_dimmer_discovery_alt_no_response.yaml) and a Velux KLR200/KUX100 pair (tests/corpus/captures/discovery/velux_kux100_discovery_alt_broadcast_no_response.yaml) both went unanswered; the older "response is 0x29" guess never had real evidence and appears to have been wrong. Directly addressed to a known device instead of broadcast, it does draw a response, but a 0x3C/0x3D challenge-response followed by CMD_DISCOVER_ALT_RESP (0x2F), not 0x29 — see tests/corpus/captures/discovery/velux_kux100_discovery_alt_addressed_challenge_response.yaml.

Definition at line 98 of file proto_constants.h.

CMD_DISCOVER_ALT_RESP

uint8_t esphome::home_io_control::CMD_DISCOVER_ALT_RESP

staticconstexpr

Initial value:

                                           =
0x2F

Reply to an addressed (non-broadcast) CMD_DISCOVER_ALT_REQ, following a 0x3C/0x3D challenge-response.

See CMD_DISCOVER_ALT_REQ's comment and tests/corpus/captures/discovery/velux_kux100_discovery_alt_addressed_challenge_response.yaml — the only capture this project has of it. Not otherwise used anywhere in this codebase (no dispatch logic added).

Definition at line 109 of file proto_constants.h.

CMD_DISCOVER_CONFIRM

uint8_t esphome::home_io_control::CMD_DISCOVER_CONFIRM = 0x2C

staticconstexpr

Confirm discovery to device.

Definition at line 96 of file proto_constants.h.

CMD_DISCOVER_CONFIRM_ACK

uint8_t esphome::home_io_control::CMD_DISCOVER_CONFIRM_ACK = 0x2D

staticconstexpr

Device acknowledges confirmation.

Definition at line 97 of file proto_constants.h.

CMD_DISCOVER_REQ

uint8_t esphome::home_io_control::CMD_DISCOVER_REQ = 0x28

staticconstexpr

Broadcast discovery request.

Definition at line 58 of file proto_constants.h.

CMD_DISCOVER_RESP

uint8_t esphome::home_io_control::CMD_DISCOVER_RESP = 0x29

staticconstexpr

Device responds with its ID and type.

Definition at line 59 of file proto_constants.h.

CMD_DISCOVER_SPE_REQ

uint8_t esphome::home_io_control::CMD_DISCOVER_SPE_REQ

staticconstexpr

Initial value:

                                          =
0x2A

Broadcast roll-call answered by every device that already holds this controller's system key, regardless of device type.

A device that holds no key yet — one in learning mode, mid-pairing — has nothing to authenticate the request against and stays silent, so this enumerates already-managed devices and cannot discover new ones. Do not offer it as a pairing-discovery command: it can only ever add replies from devices already paired, never help reach an unpaired one. The 12-byte payload authenticates itself in a single frame — 6 random challenge bytes followed by a 6-byte HMAC over the command byte alone — instead of the usual 0x3C/0x3D round trip, which is what lets it be broadcast; create_discovery_request() (proto_commands.cpp) builds it to match. Real captured bytes: tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml (request shape, HMAC recomputed under that installation's key before the capture was re-keyed) and tests/corpus/captures/discovery/somfy_awning_discovery_spe_paired_rollcall.yaml plus tests/corpus/captures/discovery/somfy_izymo_dimmer_discovery_spe_paired_rollcall.yaml (two awnings and a dimmer answering one broadcast). No dispatch path consumes the reply yet; classify_pairing_discovery_response() accepts only 0x29 and must not be extended to accept 0x2B, because a roll-call reply from an already-paired device is not a newly-discovered one and must never enter the pairing flow. See CMD_DISCOVER_SPE_RESP.

Definition at line 60 of file proto_constants.h.

CMD_DISCOVER_SPE_RESP

uint8_t esphome::home_io_control::CMD_DISCOVER_SPE_RESP

staticconstexpr

Initial value:

                                           =
0x2B

Roll-call reply to CMD_DISCOVER_SPE_REQ, sent only by devices that already hold the requesting controller's system key.

The payload is the same DISCOVERY_RESP_FULL_SIZE layout as a CMD_DISCOVER_RESP (0x29), so every DISCOVERY_RESP_*_OFFSET constant below applies unchanged — packed type/subtype at data[0..1], backbone address at DISCOVERY_RESP_BACKBONE_OFFSET, manufacturer at DISCOVERY_RESP_MANUFACTURER_OFFSET, Multi Information Byte at DISCOVERY_RESP_FLAGS_OFFSET, timestamp at DISCOVERY_RESP_TIMESTAMP_OFFSET — and PairingEngine::parse_device_from_discovery() decodes a 0x2B correctly with no special-casing. Real captured replies (two awnings and a dimmer) are in tests/corpus/captures/discovery/somfy_awning_discovery_spe_paired_rollcall.yaml and tests/corpus/captures/discovery/somfy_izymo_dimmer_discovery_spe_paired_rollcall.yaml. The timestamp is the field that advances between successive replies from one device; it is not a response to the request's random challenge, since that HMAC covers only the constant command byte. Treat a reply as self-description, not proof of identity: nothing in it is bound to the request, so report it, never act on it. No dispatch path consumes a 0x2B yet.

Definition at line 80 of file proto_constants.h.

CMD_ERROR_RESP

uint8_t esphome::home_io_control::CMD_ERROR_RESP = 0xFE

staticconstexpr

Error response to any command.

Definition at line 244 of file proto_constants.h.

CMD_EXECUTE

uint8_t esphome::home_io_control::CMD_EXECUTE = 0x00

staticconstexpr

Set position/open/close/stop — requires authentication.

Definition at line 24 of file proto_constants.h.

CMD_GET_GENERAL_INFO3

uint8_t esphome::home_io_control::CMD_GET_GENERAL_INFO3

staticconstexpr

Initial value:

                                           =
0x58

Observed on the wire (tests/corpus/captures/probe/velux_kig300_probe_capability_burst.yaml) with no payload.

Content undecoded. Not sent or handled anywhere in this codebase.

Definition at line 210 of file proto_constants.h.

CMD_GET_GENERAL_INFO3_RESP

uint8_t esphome::home_io_control::CMD_GET_GENERAL_INFO3_RESP

staticconstexpr

Initial value:

                                                =
0x59

Never captured on our own wire.

This constant exists so a received 0x59 frame renders by name instead of as UNKNOWN_CMD. Not sent or handled anywhere in this codebase.

Definition at line 213 of file proto_constants.h.

CMD_GET_INFO1

uint8_t esphome::home_io_control::CMD_GET_INFO1

staticconstexpr

Initial value:

                                   =
0x54

Request device general info 1.

Sent by the get_info1 diagnostic probe (docs/radio_diagnostics.md, ADR 0024); field-observed on air from a real hub.

Definition at line 196 of file proto_constants.h.

CMD_GET_INFO1_RESP

uint8_t esphome::home_io_control::CMD_GET_INFO1_RESP = 0x55

staticconstexpr

Device general info 1 response.

Still never captured on our wire or in any field log, and nothing decodes it — accepted by the soft-PHY only so a probe reply is not dropped as an unknown command.

Definition at line 199 of file proto_constants.h.

CMD_GET_INFO2

uint8_t esphome::home_io_control::CMD_GET_INFO2 = 0x56

staticconstexpr

Request device type/model info.

The only thing that sends it is the get_info2 diagnostic probe; the corpus has no fixture for the request itself – every 0x57 capture on hand is a reply to someone else's request. Closing this needs a fresh device-add on owned hardware, ingested with --rekey (tests/corpus/README.md).

Definition at line 203 of file proto_constants.h.

CMD_GET_INFO2_RESP

uint8_t esphome::home_io_control::CMD_GET_INFO2_RESP = 0x57

staticconstexpr

Device type/model response.

Definition at line 209 of file proto_constants.h.

CMD_GET_NAME

uint8_t esphome::home_io_control::CMD_GET_NAME = 0x50

staticconstexpr

Request device name.

Definition at line 192 of file proto_constants.h.

CMD_GET_NAME_RESP

uint8_t esphome::home_io_control::CMD_GET_NAME_RESP = 0x51

staticconstexpr

Device name response.

Definition at line 193 of file proto_constants.h.

CMD_IDENTIFY

uint8_t esphome::home_io_control::CMD_IDENTIFY = 0x1E

staticconstexpr

Device physical identification / jog — requires authentication.

Definition at line 52 of file proto_constants.h.

CMD_KEY_CONFIRM

uint8_t esphome::home_io_control::CMD_KEY_CONFIRM = 0x33

staticconstexpr

Device confirms key was received.

Definition at line 130 of file proto_constants.h.

CMD_KEY_INIT

uint8_t esphome::home_io_control::CMD_KEY_INIT = 0x31

staticconstexpr

Initiate key transfer to device.

Definition at line 128 of file proto_constants.h.

CMD_KEY_TRANSFER

uint8_t esphome::home_io_control::CMD_KEY_TRANSFER = 0x32

staticconstexpr

Send encrypted system key to device.

Definition at line 129 of file proto_constants.h.

CMD_LAUNCH_KEY_TRANSFER

uint8_t esphome::home_io_control::CMD_LAUNCH_KEY_TRANSFER

staticconstexpr

Initial value:

                                             =
0x38

Device-initiated ("pull") key transfer request: documented elsewhere as a command ID plus a 6-byte challenge, nothing more — never observed in our corpus or in any field log, and not sent or handled anywhere in this codebase — the constant is used only to construct a hypothetical device-side IV in tests/proto_crypto_test.cpp, exercising the crypto primitive, not a dispatch path.

Definition at line 151 of file proto_constants.h.

CMD_ONEWAY_ADD_CONTROLLER

uint8_t esphome::home_io_control::CMD_ONEWAY_ADD_CONTROLLER

staticconstexpr

Initial value:

                                               =
0x30

1W "add controller" — a 1W device broadcasts this while its key-copy gesture is active, handing its network's wrapped system key to whichever controller is listening.

Its 20-byte declared payload (enc_key[16] + man_id[1] + data[1] + sequence[2]) plus a genuine 6-byte MAC does not fit inside CTRL0's 5-bit length field together (29 + 6 = 35, unrepresentable in 5 bits), so the MAC rides after the declared length instead, still under the CRC — see IoFrame::has_mac and frame_carries_mac_trailer() (proto_frame.h). Reference: tests/corpus/captures/enrollment/reference_1w_enrollment_add_controller_kat.yaml.

Definition at line 115 of file proto_constants.h.

CMD_ONEWAY_REMOVE

uint8_t esphome::home_io_control::CMD_ONEWAY_REMOVE = 0x39

staticconstexpr

1W "remove controller" (un-pair a 1W remote from a device); same payload shape as 0x2E.

Definition at line 124 of file proto_constants.h.

CMD_PRIVATE

uint8_t esphome::home_io_control::CMD_PRIVATE = 0x03

staticconstexpr

Get device status — no authentication needed.

Definition at line 26 of file proto_constants.h.

CMD_PRIVATE2

uint8_t esphome::home_io_control::CMD_PRIVATE2

staticconstexpr

Initial value:

                                  =
0x0C

Content otherwise undecoded by the wire parser.

Its request payload matches CMD_EXECUTE's POS_FAVORITE/POS_VENT_MODIFIER stored-position selector with the execution prefix stripped, so it reads like a stored-position readback rather than a live telemetry poll — see the somfy_rs100_* / somfy_oximo40_* captures and multi_somfy_probe_private2_{long_form,short_form}.yaml for real request/response pairs. Not handled by any dispatch path in this codebase.

Definition at line 28 of file proto_constants.h.

CMD_PRIVATE2_RESP

uint8_t esphome::home_io_control::CMD_PRIVATE2_RESP = 0x0D

staticconstexpr

Response to CMD_PRIVATE2. See CMD_PRIVATE2's comment.

Definition at line 35 of file proto_constants.h.

CMD_PRIVATE_RESP

uint8_t esphome::home_io_control::CMD_PRIVATE_RESP = 0x04

staticconstexpr

Response to 0x00 and 0x03 (contains position data).

Definition at line 27 of file proto_constants.h.

CMD_READ_GROUPS

uint8_t esphome::home_io_control::CMD_READ_GROUPS

staticconstexpr

Initial value:

                                     =
0xF1

Named "Actuator: Read Groups" / "ActuatorAnyConfigIsLocal" (uncertain) / "Service ACK" — three candidate names, one itself flagged uncertain.

Never observed in our corpus or in any field log, and not sent or handled anywhere in this codebase.

Definition at line 231 of file proto_constants.h.

CMD_REBOOT

uint8_t esphome::home_io_control::CMD_REBOOT

staticconstexpr

Initial value:

                                =
0xF2

Named "Reboot" / "Service Status" — two candidate names, one of them destructive-sounding, on no field evidence at all.

Never observed in our corpus or in any field log, and not sent or handled anywhere in this codebase; treat the "reboot" reading with particular caution — it is a guess.

Definition at line 235 of file proto_constants.h.

CMD_SEND_RAW_MESSAGE

uint8_t esphome::home_io_control::CMD_SEND_RAW_MESSAGE

staticconstexpr

Initial value:

                                          =
0xF0

Named "Send Raw Message" / "Find Hardware" — two candidate names, neither settled.

Never observed in our corpus or in any field log, and not sent or handled anywhere in this codebase.

Definition at line 227 of file proto_constants.h.

CMD_SERVICE_STATUS_ACK

uint8_t esphome::home_io_control::CMD_SERVICE_STATUS_ACK = 0xF3

staticconstexpr

No description available at all for this opcode, not even a hedge.

Never observed in our corpus or in any field log, and not sent or handled anywhere in this codebase.

Definition at line 240 of file proto_constants.h.

CMD_SET_CONFIG1

uint8_t esphome::home_io_control::CMD_SET_CONFIG1 = 0x6F

staticconstexpr

Configure device to auto-send status updates.

Definition at line 219 of file proto_constants.h.

CMD_SET_CONFIG1_RESP

uint8_t esphome::home_io_control::CMD_SET_CONFIG1_RESP

staticconstexpr

Initial value:

                                          =
0x70

Config response, otherwise undocumented.

Never observed in our corpus or in any field log, and not sent or handled anywhere in this codebase beyond the generic "is this a known command byte" check in radio_soft_phy.cpp.

Definition at line 220 of file proto_constants.h.

CMD_SET_NAME

uint8_t esphome::home_io_control::CMD_SET_NAME = 0x52

staticconstexpr

Set device name (authenticated).

Definition at line 194 of file proto_constants.h.

CMD_SET_NAME_RESP

uint8_t esphome::home_io_control::CMD_SET_NAME_RESP = 0x53

staticconstexpr

Device-name write response.

Definition at line 195 of file proto_constants.h.

CMD_SET_SENSOR

uint8_t esphome::home_io_control::CMD_SET_SENSOR

staticconstexpr

Initial value:

                                    =
0x19

Inject sensor value into a device.

First real-world capture (issue #27, community, a real Somfy TaHoma Switch writing directly to a real Sunea io screen it already owned) is tests/corpus/captures/exchange/somfy_awning_exchange_set_sensor_sx1276.yaml — a single-byte payload, values 0x02 and then 0x04 seen ~212ms apart. Likely the mechanism a real hub uses to push a wind/rain/sun sensor reading into a device (the mirror image of reading a rain/limitation state back out, which issue #98 has been chasing separately) — not confirmed, and no CMD_SET_SENSOR_ACK was captured either, so the full round trip and payload semantics remain unknown. No builder or dispatch path exists anywhere in this codebase.

Definition at line 38 of file proto_constants.h.

CMD_SET_SENSOR_ACK

uint8_t esphome::home_io_control::CMD_SET_SENSOR_ACK = 0x1A

staticconstexpr

Acknowledgment to CMD_SET_SENSOR.

Never observed on the wire — see CMD_SET_SENSOR.

Definition at line 48 of file proto_constants.h.

CMD_STATUS_UPDATE

uint8_t esphome::home_io_control::CMD_STATUS_UPDATE = 0x71

staticconstexpr

Device-initiated status update (needs auth).

Definition at line 224 of file proto_constants.h.

CMD_STATUS_UPDATE_RESP

uint8_t esphome::home_io_control::CMD_STATUS_UPDATE_RESP = 0x72

staticconstexpr

Acknowledge status update.

Definition at line 225 of file proto_constants.h.

CMD_UNKNOWN4A_REQ

uint8_t esphome::home_io_control::CMD_UNKNOWN4A_REQ

staticconstexpr

Initial value:

                                       =
0x4A

Content undecoded.

The leading published interpretation of this opcode is "Delete File" (a large-data-transfer / "ioblob" request), with "Rename File" as a conflicting second reading — both writes, and no project this codebase draws on has ever transmitted it. Never captured on the wire either. This constant exists solely so a received 0x4A frame renders by name in the log instead of as UNKNOWN_CMD; it must never be sent, and no builder for it exists anywhere in this codebase — see CMD_ONEWAY_ADD_CONTROLLER for the same "named but never sent" precedent, and docs/adr/ for the standing decision not to add one.

Definition at line 176 of file proto_constants.h.

CMD_UNKNOWN4A_RESP

uint8_t esphome::home_io_control::CMD_UNKNOWN4A_RESP

staticconstexpr

Initial value:

                                        =
0x4B

Observed on the wire (tests/corpus/captures/probe/velux_kig300_probe_capability_burst.yaml) answering an ON_OFF_SWITCH-type device's traffic, but its request opcode is unconfirmed — it is not established to be CMD_UNKNOWN4A_REQ's reply rather than CMD_GET_GENERAL_INFO3's.

Content undecoded. Not sent or handled anywhere in this codebase.

Definition at line 185 of file proto_constants.h.

CMD_WRITE_PRIVATE

uint8_t esphome::home_io_control::CMD_WRITE_PRIVATE = 0x20

staticconstexpr

Write private register (climate/heating devices).

Definition at line 54 of file proto_constants.h.

CMD_WRITE_PRIVATE_ACK

uint8_t esphome::home_io_control::CMD_WRITE_PRIVATE_ACK = 0x21

staticconstexpr

Acknowledgment to CMD_WRITE_PRIVATE.

Definition at line 55 of file proto_constants.h.

COLD_BROADCAST_REPLY_PREAMBLE

uint16_t esphome::home_io_control::COLD_BROADCAST_REPLY_PREAMBLE = 80

staticconstexpr

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 broadcasting it across all 3 channels doesn't block the loop the way LONG_PREAMBLE does.

Sized above the ~13.9 ms real-device discovery-reply preamble this project's own SX1262/LR1121 discovery hop-slice tuning was measured against (issue #65 SDR analysis) — that measurement is what "reliably caught by a hopping receiver" is calibrated to here. 80 bytes ≈ 16.7 ms at the protocol's 38400 bps line rate (soft_phy_air_time_us()), budgeted as a starting point, not yet hardware-validated for this exact chip/scenario combination. Runtime-tunable via cold_broadcast_reply_preamble for exactly that reason.

Definition at line 47 of file proto_timing.h.

CRC_LSB_MASK

uint16_t esphome::home_io_control::CRC_LSB_MASK = 0x0001

staticconstexpr

Least-significant-bit mask for reflected CRC update.

Definition at line 384 of file proto_constants.h.

CRC_POLYNOMIAL_REVERSED

uint16_t esphome::home_io_control::CRC_POLYNOMIAL_REVERSED = 0x8408

staticconstexpr

Reversed CRC-CCITT polynomial used by IO-homecontrol.

Definition at line 383 of file proto_constants.h.

CTRL0_END

uint8_t esphome::home_io_control::CTRL0_END = 0x80

staticconstexpr

Control byte 0 (CTRL0) bit definitions.

CTRL0 encodes frame flags and the total frame length. Bits [4:0] = frame_length - 1 (so 0x08 means 9 bytes total).

• START (bit 6): first frame in an exchange. Its TX preamble depends on CTRL1_LOW_POWER, not on START alone: a low-power target gets the 1024-byte wake-up burst, others a normal preamble.
• END (bit 7): last frame in an exchange; set on responses and command completions.
• 1W (bit 5): 1=OneWay protocol (no response expected), 0=TwoWay (response expected). For 2W operation, the controller sets START on initial command and device replies with END; subsequent frames in an authenticated exchange also carry END. Bit 7: last frame in exchange

Definition at line 41 of file proto_frame.h.

CTRL0_LENGTH_MASK

uint8_t esphome::home_io_control::CTRL0_LENGTH_MASK = 0x1F

staticconstexpr

Bits [4:0]: frame length - 1.

Definition at line 44 of file proto_frame.h.

CTRL0_PROTOCOL_1W

uint8_t esphome::home_io_control::CTRL0_PROTOCOL_1W = 0x20

staticconstexpr

Bit 5: 1=OneWay protocol, 0=TwoWay protocol.

Definition at line 43 of file proto_frame.h.

CTRL0_START

uint8_t esphome::home_io_control::CTRL0_START = 0x40

staticconstexpr

Bit 6: first frame in exchange.

Definition at line 42 of file proto_frame.h.

CTRL1_ACK

uint8_t esphome::home_io_control::CTRL1_ACK = 0x10

staticconstexpr

Bit 4: sender can handle 2W responses (ACK-capable).

Definition at line 65 of file proto_frame.h.

CTRL1_BEACON

uint8_t esphome::home_io_control::CTRL1_BEACON = 0x80

staticconstexpr

Bit 7: beacon announcement frame.

Definition at line 68 of file proto_frame.h.

CTRL1_LOW_POWER

uint8_t esphome::home_io_control::CTRL1_LOW_POWER = 0x20

staticconstexpr

Bit 5: low-power device (e.g., solar-powered).

Definition at line 66 of file proto_frame.h.

CTRL1_PRIORITY

uint8_t esphome::home_io_control::CTRL1_PRIORITY = 0x04

staticconstexpr

Bit 2: high-priority frame.

Definition at line 64 of file proto_frame.h.

CTRL1_ROUTED

uint8_t esphome::home_io_control::CTRL1_ROUTED = 0x40

staticconstexpr

Bit 6: frame was relayed through a repeater.

Definition at line 67 of file proto_frame.h.

CTRL1_VERSION_MASK

uint8_t esphome::home_io_control::CTRL1_VERSION_MASK = 0x03

staticconstexpr

Ties FRAME_MAX_DECLARED_SIZE (proto_sizes.h) to the mask that actually defines it.

The two can't be expressed as one expression across the header boundary (proto_sizes.h can't include this header back without a cycle), so this assert is the drift guard instead. Control byte 1 (CTRL1) bit definitions. CTRL1 carries protocol metadata flags that describe the frame's routing, power mode, and priority characteristics.

• VERSION (bits [1:0]): protocol version number (usually 0 for current devices).
• PRIORITY (bit 2): marks a high-priority frame (e.g., discovery, security commands).
• ACK (bit 4): sender can handle 2W responses (set on all outbound 2W frames).
• LOW_POWER (bit 5): device is battery/solar powered; may sleep and requires long preamble to wake. Set from the target's per-device YAML low_power class (default false); drives both this bit and the start-frame preamble (see proto_commands.h, exchange_engine.cpp).
• ROUTED (bit 6): frame was relayed through a repeater node rather than direct.
• BEACON (bit 7): beacon announcement frame (device presence advertisement). Bits [1:0]: protocol version (usually 0).

Definition at line 63 of file proto_frame.h.

DEFAULT_PA_PIN_PA_BOOST

uint8_t esphome::home_io_control::DEFAULT_PA_PIN_PA_BOOST = 0x80

inlineconstexpr

SX1276 PA_CONFIG selector for the PA_BOOST output path.

Definition at line 62 of file hub_core.h.

DEFAULT_SETTLE_POLL_DELAY_MS

uint32_t esphome::home_io_control::DEFAULT_SETTLE_POLL_DELAY_MS = 3000

staticconstexpr

Default follow-up settle-poll delay used while a device may still be moving, when no explicit poll interval is configured (interval_ms == 0).

Short on purpose so hint-less devices are re-checked promptly and the motion-tracking loop terminates soon after the device comes to rest.

Definition at line 58 of file status_poll_policy.h.

DEFAULT_TCXO_VOLTAGE_SETTING_1P8V

uint8_t esphome::home_io_control::DEFAULT_TCXO_VOLTAGE_SETTING_1P8V = 0x03

inlineconstexpr

SX1262 DIO3 setting value for a 1.8 V TCXO.

Definition at line 63 of file hub_core.h.

DEFAULT_TX_POWER_DBM

uint8_t esphome::home_io_control::DEFAULT_TX_POWER_DBM = 17

inlineconstexpr

Default TX power used unless YAML overrides it.

Definition at line 61 of file hub_core.h.

DEVICE_METADATA_SIZE

uint8_t esphome::home_io_control::DEVICE_METADATA_SIZE = 2

staticconstexpr

Packed device metadata uses two bytes where the high 8 bits carry the upper type bits and the low byte carries both the remaining type bits and the 6-bit manufacturer subtype.

Definition at line 244 of file proto_device_model.h.

DEVICE_NAME_BUFFER_SIZE

uint8_t esphome::home_io_control::DEVICE_NAME_BUFFER_SIZE = 32

staticconstexpr

Device name storage including null terminator.

Definition at line 256 of file proto_device_model.h.

DEVICE_NAME_WRITE_CHAR_LIMIT

uint8_t esphome::home_io_control::DEVICE_NAME_WRITE_CHAR_LIMIT = 15

staticconstexpr

Reference write limit before the trailing null.

Definition at line 28 of file proto_codecs.h.

DEVICE_NAME_WRITE_PAYLOAD_SIZE

uint8_t esphome::home_io_control::DEVICE_NAME_WRITE_PAYLOAD_SIZE

staticconstexpr

Initial value:

                                                    =
DEVICE_NAME_WRITE_CHAR_LIMIT + 1

Fixed write payload: 15 visible chars plus trailing null/padding.

Definition at line 29 of file proto_codecs.h.

DEVICE_SUBTYPE_MASK

uint8_t esphome::home_io_control::DEVICE_SUBTYPE_MASK = 0x3F

staticconstexpr

Definition at line 247 of file proto_device_model.h.

DEVICE_TYPE_HIGH_BITS_SHIFT

uint8_t esphome::home_io_control::DEVICE_TYPE_HIGH_BITS_SHIFT = 6

staticconstexpr

Definition at line 246 of file proto_device_model.h.

DEVICE_TYPE_LOW_BITS_SHIFT

uint8_t esphome::home_io_control::DEVICE_TYPE_LOW_BITS_SHIFT = 2

staticconstexpr

Definition at line 245 of file proto_device_model.h.

DISCOVERY_FLAGS_ATT_MASK

uint8_t esphome::home_io_control::DISCOVERY_FLAGS_ATT_MASK = 0xC0

staticconstexpr

Bit masks and shifts for the Multi Information Byte fields.

Bits [7:6]: actuator turnaround time class.

Definition at line 583 of file proto_constants.h.

DISCOVERY_FLAGS_ATT_SHIFT

uint8_t esphome::home_io_control::DISCOVERY_FLAGS_ATT_SHIFT = 6

staticconstexpr

Shift for ATT field extraction.

Definition at line 584 of file proto_constants.h.

DISCOVERY_FLAGS_POWER_SAVE_MASK

uint8_t esphome::home_io_control::DISCOVERY_FLAGS_POWER_SAVE_MASK = 0x03

staticconstexpr

Bits [1:0]: power save mode.

Definition at line 593 of file proto_constants.h.

DISCOVERY_FLAGS_RF_SUPPORT

uint8_t esphome::home_io_control::DISCOVERY_FLAGS_RF_SUPPORT = 0x08

staticconstexpr

Bit 3: RF support in node (0=yes, 1=no).

Definition at line 592 of file proto_constants.h.

DISCOVERY_FLAGS_SYNC_CTRL_GRP

uint8_t esphome::home_io_control::DISCOVERY_FLAGS_SYNC_CTRL_GRP = 0x20

staticconstexpr

Bit 5: supports sync control group.

Definition at line 585 of file proto_constants.h.

DISCOVERY_RESP_BACKBONE_OFFSET

uint8_t esphome::home_io_control::DISCOVERY_RESP_BACKBONE_OFFSET = 2

staticconstexpr

Byte offsets within CMD_DISCOVER_RESP (0x29) payload data.

The full discovery response carries up to 9 bytes of device metadata: bytes 0–1 hold the packed device type/subtype (already parsed by decode_packed_device_type()), and bytes 2–8 hold additional fields. Backbone address starts at data[2] (3 bytes); cross-confirmed by CMD_ADDRESS_RESP (0x37), which returns the same 3 bytes for the same device (see that constant's comment).

Definition at line 567 of file proto_constants.h.

DISCOVERY_RESP_FLAGS_OFFSET

uint8_t esphome::home_io_control::DISCOVERY_RESP_FLAGS_OFFSET = 6

staticconstexpr

Flags byte at data[6].

Definition at line 572 of file proto_constants.h.

DISCOVERY_RESP_FULL_SIZE

uint8_t esphome::home_io_control::DISCOVERY_RESP_FULL_SIZE = 9

staticconstexpr

Full discovery response payload size.

Definition at line 574 of file proto_constants.h.

DISCOVERY_RESP_MANUFACTURER_OFFSET

uint8_t esphome::home_io_control::DISCOVERY_RESP_MANUFACTURER_OFFSET = 5

staticconstexpr

Manufacturer ID at data[5].

Definition at line 571 of file proto_constants.h.

DISCOVERY_RESP_TIMESTAMP_OFFSET

uint8_t esphome::home_io_control::DISCOVERY_RESP_TIMESTAMP_OFFSET = 7

staticconstexpr

Timestamp starts at data[7] (2 bytes).

Definition at line 573 of file proto_constants.h.

EXCHANGE_RETRY_COUNT

uint8_t esphome::home_io_control::EXCHANGE_RETRY_COUNT = 3

staticconstexpr

Attempts per command before reporting failure.

Definition at line 112 of file proto_timing.h.

EXCHANGE_RETRY_DELAY_MS

int32_t esphome::home_io_control::EXCHANGE_RETRY_DELAY_MS = 250

staticconstexpr

Gap between retries within one HA command.

Definition at line 111 of file proto_timing.h.

EXCHANGE_TOTAL_BUDGET_MS

uint16_t esphome::home_io_control::EXCHANGE_TOTAL_BUDGET_MS = 2500

staticconstexpr

Wall-clock ceiling on one whole exchange, retries included.

EXCHANGE_RETRY_COUNT tries x (long preamble + response window + retry gap) is what actually determines how long a failing command blocks the ESPHome loop, and that blocking also starves the receive path the rest of the exchange depends on. ESPHome itself warns when one operation takes longer than 2550 ms (ADR 0013); this budget must stay under that threshold.

So the retry count is a maximum, not a promise: a try only starts if the exchange has budget left. At the current 400 ms response window all three tries still fit (~2.3 s); raising the window well past the default is what starts trimming retries, since three full tries stop being affordable at that point — one long listen is the better trade there anyway.

Definition at line 159 of file proto_timing.h.

FRAME_CMD_OFFSET

uint8_t esphome::home_io_control::FRAME_CMD_OFFSET = 8

staticconstexpr

Byte offset of the command ID in a raw wire buffer.

Definition at line 47 of file proto_sizes.h.

FRAME_CRC_SIZE

uint8_t esphome::home_io_control::FRAME_CRC_SIZE = 2

staticconstexpr

Size of the on-air CRC-CCITT trailer appended after every frame (declared bytes, plus the out-of-length MAC trailer when present).

Definition at line 51 of file proto_sizes.h.

FRAME_LOG_FLAGS_BUFFER_SIZE

size_t esphome::home_io_control::FRAME_LOG_FLAGS_BUFFER_SIZE = 32

inlineconstexpr

Buffer for decoded CTRL1 flag annotations.

Definition at line 20 of file log_frame.h.

FRAME_LOG_HEX_BUFFER_SIZE

size_t esphome::home_io_control::FRAME_LOG_HEX_BUFFER_SIZE = 220

inlineconstexpr

Fits a full 32-byte frame rendered as spaced hex text.

Definition at line 19 of file log_frame.h.

FRAME_MAX_DATA_SIZE

uint8_t esphome::home_io_control::FRAME_MAX_DATA_SIZE = 23

staticconstexpr

Maximum data bytes after command ID (declared length - header).

Definition at line 46 of file proto_sizes.h.

FRAME_MAX_DECLARED_SIZE

uint8_t esphome::home_io_control::FRAME_MAX_DECLARED_SIZE = 32

staticconstexpr

Largest frame length CTRL0's 5-bit length field (bits [4:0], length - 1) can express.

This is the wire-format bound on the declared portion of a frame — the part CTRL0's length bits describe and parse()/serialize()/set_cmd() size against. It is not expressed here as CTRL0_LENGTH_MASK + 1 because CTRL0_LENGTH_MASK lives in proto_frame.h, which includes this header — referencing it back here would be a circular include. proto_frame.h carries a static_assert tying the two together right next to CTRL0_LENGTH_MASK's declaration, so this literal cannot silently drift from the mask that actually defines it.

Definition at line 38 of file proto_sizes.h.

FRAME_MAX_SIZE

uint8_t esphome::home_io_control::FRAME_MAX_SIZE = FRAME_MAX_DECLARED_SIZE

staticconstexpr

Historical name for FRAME_MAX_DECLARED_SIZE, kept as an alias rather than a second literal so the two names can never disagree — most call sites (set_cmd, serialize, parse, every fixed-size frame buffer that only ever holds a declared-length frame) predate the trailer/wire distinction and still read most naturally as "the max frame size".

Definition at line 44 of file proto_sizes.h.

FRAME_MAX_TRAILER_SIZE

uint8_t esphome::home_io_control::FRAME_MAX_TRAILER_SIZE = HMAC_SIZE

staticconstexpr

Largest out-of-length authenticator a frame can carry.

A 1W CMD 0x30 "add controller" payload (enc_key[16] + man_id[1] + data[1] + sequence[2] = 20 bytes) plus its 9-byte header is 29 bytes — already representable in CTRL0's 5-bit field — but its 6-byte MAC does not fit inside the same field's remaining headroom (29 declared + 6 MAC = 35, unrepresentable in 5 bits), so the MAC rides after the declared length instead, still under the CRC. The iohomecontrol reference implementation's _p0x30 packet struct omits an hmac field entirely (unlike its _p0x2e, whose MAC sits inside the declared length).

Definition at line 60 of file proto_sizes.h.

FRAME_MAX_WIRE_SIZE

uint8_t esphome::home_io_control::FRAME_MAX_WIRE_SIZE = FRAME_MAX_DECLARED_SIZE + FRAME_MAX_TRAILER_SIZE + FRAME_CRC_SIZE

staticconstexpr

Largest number of bytes a buffer must hold to receive or transmit any frame this project knows about, trailer and CRC included: FRAME_MAX_DECLARED_SIZE (what CTRL0 can declare).

• FRAME_MAX_TRAILER_SIZE (the out-of-length MAC, when present) + FRAME_CRC_SIZE. This is the wire bound — distinct from FRAME_MAX_DECLARED_SIZE, which is the declared bound set_cmd() still enforces. A buffer sized to the declared bound alone truncates a MAC-bearing frame; use this constant for any buffer that must survive one intact.

Definition at line 68 of file proto_sizes.h.

FRAME_MIN_SIZE

uint8_t esphome::home_io_control::FRAME_MIN_SIZE = 9

staticconstexpr

Minimum frame: CTRL0+CTRL1+DST(3)+SRC(3)+CMD(1).

Definition at line 29 of file proto_sizes.h.

FREQ_CH1

uint32_t esphome::home_io_control::FREQ_CH1 = 868250000

staticconstexpr

The protocol uses 3 frequency channels in the 868 MHz ISM band.

IO-Homecontrol uses 3 channels in the 868 MHz SRD band. In 1W (one-way) mode, only CH2 is used. In 2W (two-way) mode, the controller hops across all three channels every ~2.7ms when idle. Commands are sent on CH2; responses may arrive on any channel within the exchange wait window. Channel 1: 868.25 MHz (2W only)

Definition at line 21 of file proto_timing.h.

FREQ_CH2

uint32_t esphome::home_io_control::FREQ_CH2 = 868950000

staticconstexpr

Channel 2: 868.95 MHz (1W and 2W, TX channel).

Definition at line 22 of file proto_timing.h.

FREQ_CH3

uint32_t esphome::home_io_control::FREQ_CH3 = 869850000

staticconstexpr

Channel 3: 869.85 MHz (2W only).

Definition at line 23 of file proto_timing.h.

FXOSC

uint32_t esphome::home_io_control::FXOSC = 32000000U

staticconstexpr

SX1276 crystal oscillator frequency (32 MHz).

Used to calculate register values for bitrate, frequency deviation, and carrier frequency.

Definition at line 67 of file radio_sx1276.h.

HEATING_PAYLOAD_MAX_SIZE

size_t esphome::home_io_control::HEATING_PAYLOAD_MAX_SIZE = 6

constexpr

Largest payload any function produces — SET_TEMPERATURE's 6-byte form (iohcCozyDevice2W.cpp:125).

Definition at line 70 of file proto_heating.h.

HEATING_PAYLOAD_PREFIX

uint8_t esphome::home_io_control::HEATING_PAYLOAD_PREFIX = 0x0C

constexpr

Leading payload byte, common to every function (iohcCozyDevice2W.cpp:105 et al.).

The reference gives it no name and no explanation; its meaning is unconfirmed. Do not read a semantic (e.g. "device class") into it.

Definition at line 76 of file proto_heating.h.

HEATING_REGISTER_HIGH_BYTE

uint8_t esphome::home_io_control::HEATING_REGISTER_HIGH_BYTE = 0x01

constexpr

Payload byte at index 2 — the high byte of the 16-bit register number, constant 0x01 (registers are 0x01xx) per AtlanticThermor/README.md ("Set 0c61 01xx" / "Get 0c60 01xx").

The low byte (register selector) is per-function; see HeatingFunctionDescriptor::register_low.

Definition at line 81 of file proto_heating.h.

HEATING_TEMP_MAX_C

float esphome::home_io_control::HEATING_TEMP_MAX_C = 28.0F

constexpr

Highest setpoint this codec will encode.

iohcCozyDevice2W.cpp:125-128 only writes the low byte of the setpoint field, so that implementation tops out at 0xFF = 25.5 C — a latent bug, not the wire limit. The vendored Atlantic register map (AtlanticThermor/README.md) shows the setpoint field is a 16-bit little-endian value in tenths of a degree: its 0x0130 block carries 18 01 = 0x0118 = 280 = 28.0 C as a live setpoint. This codec writes both bytes and allows up to 28.0 C, the ceiling Atlantic radiator manuals document. The encoding above 25.5 C is corroborated by the vendored register map but still unverified on hardware — see docs/home_io_control.md.

Definition at line 66 of file proto_heating.h.

HEATING_TEMP_MIN_C

float esphome::home_io_control::HEATING_TEMP_MIN_C = 7.0F

constexpr

Lowest setpoint this codec will encode.

The conventional frost-protection setpoint. No reference evidence pins a hard lower bound; 7.0 is safely representable as wire byte 0x46.

Definition at line 55 of file proto_heating.h.

HMAC_SIZE

uint8_t esphome::home_io_control::HMAC_SIZE = 6

staticconstexpr

Authentication HMAC is 6 bytes (truncated AES output).

Definition at line 22 of file proto_sizes.h.

HOP_TIME_US

int32_t esphome::home_io_control::HOP_TIME_US = 2700

staticconstexpr

Timing constants for frequency hopping and response waiting.

Time per channel when hopping (2.7ms)

Definition at line 91 of file proto_timing.h.

INITIAL_STATUS_REQUEST_DELAY_MS

uint32_t esphome::home_io_control::INITIAL_STATUS_REQUEST_DELAY_MS = 5000

staticconstexpr

Delay before the first post-boot status request from an entity.

Definition at line 39 of file status_poll_policy.h.

IV_PADDING

uint8_t esphome::home_io_control::IV_PADDING = 0x55

staticconstexpr

Padding byte used in IV construction.

Definition at line 26 of file proto_sizes.h.

IV_SIZE

uint8_t esphome::home_io_control::IV_SIZE = 16

staticconstexpr

Initialization vector size for AES.

Definition at line 25 of file proto_sizes.h.

LATIN1_CODEPOINT_MAX

uint16_t esphome::home_io_control::LATIN1_CODEPOINT_MAX = 0x00FF

staticconstexpr

Highest Unicode code point representable in Latin-1.

Definition at line 31 of file proto_codecs.h.

LBT_MAX_RETRIES

uint8_t esphome::home_io_control::LBT_MAX_RETRIES = 5

staticconstexpr

Max carrier-sense attempts before TX anyway.

Definition at line 196 of file proto_timing.h.

LBT_RETRY_DELAY_MS

uint8_t esphome::home_io_control::LBT_RETRY_DELAY_MS = 5

staticconstexpr

Backoff between LBT checks (≥ 5ms per ETSI).

Definition at line 197 of file proto_timing.h.

LBT_RSSI_THRESHOLD_DBM

int16_t esphome::home_io_control::LBT_RSSI_THRESHOLD_DBM = -90

staticconstexpr

Listen-before-talk (LBT) parameters for ETSI EN 300 220 compliance.

Before transmitting, the radio checks that the channel RSSI is below the threshold. If the channel is busy, TX is deferred by LBT_RETRY_DELAY_MS up to LBT_MAX_RETRIES times. Channel-free threshold (ETSI: ≤ -90 dBm)

Definition at line 195 of file proto_timing.h.

LONG_PREAMBLE

uint16_t esphome::home_io_control::LONG_PREAMBLE = 1024

staticconstexpr

Preamble is a sequence of 0xAA bytes that precedes every frame.

A directed start frame to a low-power target (CTRL1_LOW_POWER set) uses the long preamble (1024 bytes = 8192 bits) as a wake-up burst for its duty-cycled receiver; every other start frame uses the runtime-tunable normal_start_preamble, which an always-listening receiver detects fine. Subsequent frames in the same exchange use a short preamble (8 bytes) since both sides are already on the same channel. The exchange engine derives all of this from the frame (exchange_engine.cpp). 1024 bytes: wake-up burst for a low-power start frame

Definition at line 32 of file proto_timing.h.

LR1110_BOOTLOADER_1001

uint16_t esphome::home_io_control::LR1110_BOOTLOADER_1001 = 0x1001

inlineconstexpr

Definition at line 51 of file lr1121_firmware_decisions.h.

LR1110_BOOTLOADER_6500

uint16_t esphome::home_io_control::LR1110_BOOTLOADER_6500 = 0x6500

inlineconstexpr

Definition at line 50 of file lr1121_firmware_decisions.h.

LR1110_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS

uint8_t esphome::home_io_control::LR1110_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS = 0x01

inlineconstexpr

Normal-mode GetVersion type bytes for the two chips an LR1121 is most easily confused with — companions to LR1121_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS above, used only to name the chip family in a REJECT_WRONG_CHIP message.

Last checked 2026-08-05.

Definition at line 28 of file lr1121_firmware_decisions.h.

LR1120_BOOTLOADER_2000

uint16_t esphome::home_io_control::LR1120_BOOTLOADER_2000 = 0x2000

inlineconstexpr

Bootloader versions reported by the two chips an LR1121 is most easily confused with — used only to name the chip family in a REJECT_WRONG_CHIP message.

Same snapshot discipline as LR1121_BOOTLOADER_2100/2101; last checked 2026-08-05.

Definition at line 48 of file lr1121_firmware_decisions.h.

LR1120_BOOTLOADER_2001

uint16_t esphome::home_io_control::LR1120_BOOTLOADER_2001 = 0x2001

inlineconstexpr

Definition at line 49 of file lr1121_firmware_decisions.h.

LR1120_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS

uint8_t esphome::home_io_control::LR1120_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS = 0x02

inlineconstexpr

Definition at line 29 of file lr1121_firmware_decisions.h.

LR1121_BOOTLOADER_2100

uint16_t esphome::home_io_control::LR1121_BOOTLOADER_2100 = 0x2100

inlineconstexpr

LR1121 bootloader versions, from Semtech's published compatibility matrix.

An LR1121 reports one of these two; LR1120 reports 0x2000/0x2001 and LR1110 0x6500/0x1001, which is what makes checking against these two a chip-family check as well as a capability check.

Definition at line 42 of file lr1121_firmware_decisions.h.

LR1121_BOOTLOADER_2101

uint16_t esphome::home_io_control::LR1121_BOOTLOADER_2101 = 0x2101

inlineconstexpr

Definition at line 43 of file lr1121_firmware_decisions.h.

LR1121_BOOTLOADER_TYPE_FOR_FIRMWARE_DECISIONS

uint8_t esphome::home_io_control::LR1121_BOOTLOADER_TYPE_FOR_FIRMWARE_DECISIONS = 0xDF

inlineconstexpr

LR1121 GetVersion type byte reported while running the bootloader (LR11XX_TYPE_PRODUCTION_MODE) — must match radio_lr1121_firmware_updater.h's LR1121_UPDATER_BOOTLOADER_TYPE (0xDF).

Kept as a separate constant for the same dependency-free reason as LR1121_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS above. Note this byte identifies production silicon, not chip family — bootloader type is 0xDF on an LR1120 or LR1110 too, which is why chip family is decided from the bootloader version, not this byte.

Definition at line 37 of file lr1121_firmware_decisions.h.

LR1121_BUSY_TIMEOUT_MS

uint32_t esphome::home_io_control::LR1121_BUSY_TIMEOUT_MS = 3000

staticconstexpr

How long SoftPhyDriverBase::wait_busy_() waits for BUSY to drop before declaring the chip failed.

The LR11xx runs an internal boot ROM after reset before BUSY is meaningful — cross-checked against RadioLib's LRxxxx::reset(), which waits ~300ms ("typical transition duration should be 273 ms") and then polls BUSY with a 3s timeout; matched here exactly rather than picking an arbitrary shorter value, since the only cost of a longer timeout is on the already-failing path (a genuinely dead chip takes a few seconds longer to report failure). Much longer than SX1262's (see SX1262_BUSY_TIMEOUT_MS in radio_sx1262.h) — different chips, different boot behavior, not a value that should be unified.

Definition at line 228 of file radio_lr1121.h.

LR1121_CALIBRATE_ALL_BLOCKS

uint8_t esphome::home_io_control::LR1121_CALIBRATE_ALL_BLOCKS = 0x3F

staticconstexpr

Calibrate "all blocks" bitmask.

LR11xx calibration blocks are LF-RC(0)/HF-RC(1)/PLL(2)/ ADC(3)/IMG(4)/PLL-TX(5), so "all" = 0x3F — NOT the SX126x value (0x7F), which uses a different bit layout for a different chip.

Definition at line 154 of file radio_lr1121.h.

LR1121_CMD_CALIBRATE

uint16_t esphome::home_io_control::LR1121_CMD_CALIBRATE = 0x010F

staticconstexpr

cross-checked

Definition at line 50 of file radio_lr1121.h.

LR1121_CMD_CALIBRATE_IMAGE

uint16_t esphome::home_io_control::LR1121_CMD_CALIBRATE_IMAGE = 0x0111

staticconstexpr

cross-checked (RadioLib calibrateImageRejection)

Definition at line 51 of file radio_lr1121.h.

LR1121_CMD_CLEAR_ERRORS

uint16_t esphome::home_io_control::LR1121_CMD_CLEAR_ERRORS

staticconstexpr

Initial value:

                                              =
0x010E

hardware-verified (called on every init/RX cycle, never rejected — see log_command_status_())

Definition at line 44 of file radio_lr1121.h.

LR1121_CMD_CLEAR_IRQ

uint16_t esphome::home_io_control::LR1121_CMD_CLEAR_IRQ = 0x0114

staticconstexpr

cross-checked

Definition at line 54 of file radio_lr1121.h.

LR1121_CMD_GET_ERRORS

uint16_t esphome::home_io_control::LR1121_CMD_GET_ERRORS = 0x010D

staticconstexpr

cross-checked (2-byte response)

Definition at line 43 of file radio_lr1121.h.

LR1121_CMD_GET_PKT_STATUS

uint16_t esphome::home_io_control::LR1121_CMD_GET_PKT_STATUS

staticconstexpr

Initial value:

                                                =
0x0204

cross-checked (Semtech SWDR001 lr11xx_radio.c :: lr11xx_radio_get_gfsk_pkt_status — 0 request params, 4-byte GFSK response: [rssi_sync, rssi_avg, rx_len, status_flags], rssi_sync/avg both decode via -(raw>>1) dBm, same formula as LR1121_CMD_GET_RSSI_INST)

Definition at line 58 of file radio_lr1121.h.

LR1121_CMD_GET_RSSI_INST

uint16_t esphome::home_io_control::LR1121_CMD_GET_RSSI_INST = 0x0205

staticconstexpr

cross-checked

Definition at line 62 of file radio_lr1121.h.

LR1121_CMD_GET_RX_BUFFER_STATUS

uint16_t esphome::home_io_control::LR1121_CMD_GET_RX_BUFFER_STATUS = 0x0203

staticconstexpr

cross-checked

Definition at line 57 of file radio_lr1121.h.

LR1121_CMD_GET_STATUS

uint16_t esphome::home_io_control::LR1121_CMD_GET_STATUS = 0x0100

staticconstexpr

cross-checked

Definition at line 41 of file radio_lr1121.h.

LR1121_CMD_GET_VERSION

uint16_t esphome::home_io_control::LR1121_CMD_GET_VERSION = 0x0101

staticconstexpr

cross-checked

Definition at line 42 of file radio_lr1121.h.

LR1121_CMD_READ_BUFFER

uint16_t esphome::home_io_control::LR1121_CMD_READ_BUFFER = 0x010A

staticconstexpr

cross-checked

Definition at line 47 of file radio_lr1121.h.

LR1121_CMD_SET_DIO_AS_RF_SWITCH

uint16_t esphome::home_io_control::LR1121_CMD_SET_DIO_AS_RF_SWITCH = 0x0112

staticconstexpr

cross-checked

Definition at line 52 of file radio_lr1121.h.

LR1121_CMD_SET_DIO_IRQ_PARAMS

uint16_t esphome::home_io_control::LR1121_CMD_SET_DIO_IRQ_PARAMS = 0x0113

staticconstexpr

cross-checked

Definition at line 53 of file radio_lr1121.h.

LR1121_CMD_SET_GFSK_SYNC_WORD

uint16_t esphome::home_io_control::LR1121_CMD_SET_GFSK_SYNC_WORD = 0x0206

staticconstexpr

cross-checked

Definition at line 63 of file radio_lr1121.h.

LR1121_CMD_SET_MODULATION_PARAMS

uint16_t esphome::home_io_control::LR1121_CMD_SET_MODULATION_PARAMS = 0x020F

staticconstexpr

cross-checked

Definition at line 68 of file radio_lr1121.h.

LR1121_CMD_SET_PA_CONFIG

uint16_t esphome::home_io_control::LR1121_CMD_SET_PA_CONFIG = 0x0215

staticconstexpr

cross-checked

Definition at line 72 of file radio_lr1121.h.

LR1121_CMD_SET_PACKET_PARAMS

uint16_t esphome::home_io_control::LR1121_CMD_SET_PACKET_PARAMS = 0x0210

staticconstexpr

cross-checked

Definition at line 69 of file radio_lr1121.h.

LR1121_CMD_SET_PACKET_TYPE

uint16_t esphome::home_io_control::LR1121_CMD_SET_PACKET_TYPE = 0x020E

staticconstexpr

cross-checked

Definition at line 67 of file radio_lr1121.h.

LR1121_CMD_SET_RF_FREQUENCY

uint16_t esphome::home_io_control::LR1121_CMD_SET_RF_FREQUENCY = 0x020B

staticconstexpr

cross-checked

Definition at line 66 of file radio_lr1121.h.

LR1121_CMD_SET_RX

uint16_t esphome::home_io_control::LR1121_CMD_SET_RX = 0x0209

staticconstexpr

cross-checked

Definition at line 64 of file radio_lr1121.h.

LR1121_CMD_SET_RX_TX_FALLBACK_MODE

uint16_t esphome::home_io_control::LR1121_CMD_SET_RX_TX_FALLBACK_MODE = 0x0213

staticconstexpr

cross-checked

Definition at line 71 of file radio_lr1121.h.

LR1121_CMD_SET_STANDBY

uint16_t esphome::home_io_control::LR1121_CMD_SET_STANDBY = 0x011C

staticconstexpr

cross-checked

Definition at line 56 of file radio_lr1121.h.

LR1121_CMD_SET_TCXO_MODE

uint16_t esphome::home_io_control::LR1121_CMD_SET_TCXO_MODE = 0x0117

staticconstexpr

cross-checked

Definition at line 55 of file radio_lr1121.h.

LR1121_CMD_SET_TX

uint16_t esphome::home_io_control::LR1121_CMD_SET_TX = 0x020A

staticconstexpr

cross-checked

Definition at line 65 of file radio_lr1121.h.

LR1121_CMD_SET_TX_PARAMS

uint16_t esphome::home_io_control::LR1121_CMD_SET_TX_PARAMS = 0x0211

staticconstexpr

cross-checked

Definition at line 70 of file radio_lr1121.h.

LR1121_CMD_WRITE_BUFFER

uint16_t esphome::home_io_control::LR1121_CMD_WRITE_BUFFER = 0x0109

staticconstexpr

cross-checked

Definition at line 46 of file radio_lr1121.h.

LR1121_CMD_WRITE_REG_MEM_MASK32

uint16_t esphome::home_io_control::LR1121_CMD_WRITE_REG_MEM_MASK32

staticconstexpr

Initial value:

                                                      =
0x010C

cross-checked (Semtech SWDR001 lr11xx_radio.c / RadioLib LR11x0_commands.h)

Definition at line 48 of file radio_lr1121.h.

LR1121_DEVICE_TYPE

uint8_t esphome::home_io_control::LR1121_DEVICE_TYPE = 0x03

staticconstexpr

cross-checked against RadioLib and the datasheet

Definition at line 106 of file radio_lr1121.h.

LR1121_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS

uint8_t esphome::home_io_control::LR1121_DEVICE_TYPE_FOR_FIRMWARE_DECISIONS = 0x03

inlineconstexpr

LR1121 GetVersion type byte in normal mode — must match radio_lr1121.h's LR1121_DEVICE_TYPE (0x03).

Kept as a separate constant, not a shared header include, so this header stays dependency-free; see the file header for why. A static_assert in tests/radio_lr1121_firmware_updater_test.cpp (a translation unit that already includes both headers) guards the two from silently drifting apart.

Definition at line 23 of file lr1121_firmware_decisions.h.

LR1121_DISCOVERY_HOP_SLICE_MS

uint16_t esphome::home_io_control::LR1121_DISCOVERY_HOP_SLICE_MS = 7

staticconstexpr

Per-channel dwell while LR1121 pairing discovery hops across channels.

Measured independently on LR1121 hardware rather than inherited from SX1262_DISCOVERY_HOP_SLICE_MS — that constant's short-dwell reasoning applies equally here, but the two chips are validated separately and could in principle diverge, so this stays its own literal rather than an alias.

Definition at line 159 of file tuning_config.h.

LR1121_FALLBACK_STDBY_XOSC

uint8_t esphome::home_io_control::LR1121_FALLBACK_STDBY_XOSC = 0x02

staticconstexpr

SetRxTxFallbackMode value for STDBY_XOSC.

LR11xx fallback-mode is a small sequential enum (FS=0x00, STDBY_RC=0x01, STDBY_XOSC=0x02), unlike SX126x's raw standby-mode byte (0x30) reused directly in that field.

Definition at line 159 of file radio_lr1121.h.

LR1121_GFSK_CRC_OFF

uint8_t esphome::home_io_control::LR1121_GFSK_CRC_OFF = 0x01

staticconstexpr

cross-checked (same encoding as SX126x)

Definition at line 141 of file radio_lr1121.h.

LR1121_GFSK_PACKET_FIXED_LENGTH

uint8_t esphome::home_io_control::LR1121_GFSK_PACKET_FIXED_LENGTH = 0x00

staticconstexpr

cross-checked (same encoding as SX126x)

Definition at line 142 of file radio_lr1121.h.

LR1121_IMAGE_CAL_FREQ1

uint8_t esphome::home_io_control::LR1121_IMAGE_CAL_FREQ1 = 0xD7

staticconstexpr

Banded image calibration for 868.25-869.85MHz +/-4MHz (~860-876MHz), matching RadioLib's setFrequency() margin.

CalibImage params are {floor((fmin-1)/4), ceil((fmax+1)/4)}.

Definition at line 199 of file radio_lr1121.h.

LR1121_IMAGE_CAL_FREQ2

uint8_t esphome::home_io_control::LR1121_IMAGE_CAL_FREQ2 = 0xDB

staticconstexpr

Definition at line 200 of file radio_lr1121.h.

LR1121_IRQ_ACTIVITY_MASK

uint32_t esphome::home_io_control::LR1121_IRQ_ACTIVITY_MASK

staticconstexpr

Initial value:

                                               =
LR1121_IRQ_TX_DONE | LR1121_IRQ_RX_DONE | LR1121_IRQ_SYNC_WORD_VALID | LR1121_IRQ_CRC_ERR | LR1121_IRQ_TIMEOUT

IRQ bits that represent a terminal radio event — a frame finished decoding, an outbound frame completed, or the chip gave up on its own.

Deliberately excludes PREAMBLE_DETECTED, even though it's part of LR1121_IRQ_DIO_ENABLE_MASK: a preamble alone means a frame may still be arriving, so SoftPhyDriverBase's poll_until_activity_()/check_for_packet() (gated by RadioLR1121::activity_irq_mask) must not treat it as terminal — doing so would tear down RX mid-reception.

Definition at line 92 of file radio_lr1121.h.

LR1121_IRQ_CRC_ERR

uint32_t esphome::home_io_control::LR1121_IRQ_CRC_ERR = 1UL << 7

staticconstexpr

Definition at line 83 of file radio_lr1121.h.

LR1121_IRQ_DIO_ENABLE_MASK

uint32_t esphome::home_io_control::LR1121_IRQ_DIO_ENABLE_MASK

staticconstexpr

Initial value:

= LR1121_IRQ_TX_DONE | LR1121_IRQ_RX_DONE |
  LR1121_IRQ_PREAMBLE_DETECTED | LR1121_IRQ_SYNC_WORD_VALID |
  LR1121_IRQ_TIMEOUT

DIO-routed IRQ enable mask: TxDone|RxDone|PreambleDetected|SyncWordValid|Timeout.

Deliberately excludes CrcErr from the DIO-routed set, unlike SX1262; CrcErr is still visible in the raw status word for capture diagnostics.

Definition at line 98 of file radio_lr1121.h.

LR1121_IRQ_PREAMBLE_DETECTED

uint32_t esphome::home_io_control::LR1121_IRQ_PREAMBLE_DETECTED = 1UL << 4

staticconstexpr

Definition at line 81 of file radio_lr1121.h.

LR1121_IRQ_RX_DONE

uint32_t esphome::home_io_control::LR1121_IRQ_RX_DONE = 1UL << 3

staticconstexpr

Definition at line 80 of file radio_lr1121.h.

LR1121_IRQ_SYNC_WORD_VALID

uint32_t esphome::home_io_control::LR1121_IRQ_SYNC_WORD_VALID = 1UL << 5

staticconstexpr

Definition at line 82 of file radio_lr1121.h.

LR1121_IRQ_TIMEOUT

uint32_t esphome::home_io_control::LR1121_IRQ_TIMEOUT = 1UL << 10

staticconstexpr

Definition at line 84 of file radio_lr1121.h.

LR1121_IRQ_TX_DONE

uint32_t esphome::home_io_control::LR1121_IRQ_TX_DONE = 1UL << 2

staticconstexpr

Definition at line 79 of file radio_lr1121.h.

LR1121_KNOWN_BOOTLOADER_REQUIREMENTS

Lr1121BootloaderRequirement esphome::home_io_control::LR1121_KNOWN_BOOTLOADER_REQUIREMENTS[]

inlineconstexpr

Initial value:

                                                                                  = {
    {0x0101, LR1121_BOOTLOADER_2100},
    {0x0102, LR1121_BOOTLOADER_2100},
    {0x0103, LR1121_BOOTLOADER_2100},
    {0x0104, LR1121_BOOTLOADER_2101},
}

Bootloader requirements we know about, copied from Semtech's published pairings (SWTL001/application/src/lr11xx_update_utils.c :: compatibility_matrix[]): 0x0101/0x0102/0x0103 need bootloader 0x2100, 0x0104 needs 0x2101.

This is an ADVISORY list of pairs we can warn about, not a compatibility authority — it is a point-in-time snapshot and a target absent from it is "unverified", never "incompatible". Extending this when Semtech publishes a new image is a one-line edit; it belongs next to LR1121_KNOWN_LATEST_FW_* (radio_lr1121.h) as the same kind of snapshot, with the same staleness discipline. Last checked 2026-08-05.

Definition at line 103 of file lr1121_firmware_decisions.h.

LR1121_KNOWN_LATEST_FW_MAJOR

uint8_t esphome::home_io_control::LR1121_KNOWN_LATEST_FW_MAJOR = 0x01

staticconstexpr

Newest LR1121 transceiver firmware known at the time this file was last updated, per the version-numbered filenames and CHANGELOG.md at https://github.com/Lora-net/radio_firmware_images/tree/master/lr1121/transceiver — the same two bytes GetVersion reports as fw_major/fw_minor (e.g.

lr1121_transceiver_0104.bin is major=0x01, minor=0x04). Deliberately NOT queried live (baked in, per design decision) — this is a point-in-time snapshot that will go stale as Semtech ships new firmware, and needs a manual refresh here when it does.

Last checked 2026-08-05: latest is 0x0104 (2026-04-01), which per that changelog fixes CVE-2025-14857/-14858/-14859 (see https://www.semtech.com/company/security/security-bulletins) on top of earlier feature/bugfix releases — not just a cosmetic version bump.

Reachability caveat: this project's lr1121_firmware_update: feature (docs/home_io_control.md) can flash any published image, but 0x0104 requires bootloader 0x2101. Reaching it from the common 0x2100 bootloader needs the separate, opt-in bootloader rewrite (ADR 0021) — an irreversible operation gated behind its own arming switch — so without that opted in, 0x0103 is the practical ceiling. The "update available" line below can therefore point at a version that is not reachable on a given chip as currently configured; the flash feature's own boot-time bootloader-version report is what tells a user which case they are in.

Definition at line 127 of file radio_lr1121.h.

LR1121_KNOWN_LATEST_FW_MINOR

uint8_t esphome::home_io_control::LR1121_KNOWN_LATEST_FW_MINOR = 0x04

staticconstexpr

Definition at line 128 of file radio_lr1121.h.

LR1121_LOADER_2100

uint16_t esphome::home_io_control::LR1121_LOADER_2100 = 0x2100

inlineconstexpr

Version the lr1121_loader_2100.bin bootloader-*loader* image reports of itself.

Numerically identical to LR1121_BOOTLOADER_2100, but a distinct concept: this is the loader firmware's own self-reported version, which Semtech's compatibility rule requires to equal the bootloader version currently running before the loader may be used – not a "requires bootloader >= X" rule like LR1121_KNOWN_BOOTLOADER_REQUIREMENTS below.

Definition at line 58 of file lr1121_firmware_decisions.h.

LR1121_PACKET_TYPE_GFSK

uint8_t esphome::home_io_control::LR1121_PACKET_TYPE_GFSK = 0x01

staticconstexpr

cross-checked against RadioLib

Definition at line 140 of file radio_lr1121.h.

LR1121_POST_TX_SETTLE_US

uint16_t esphome::home_io_control::LR1121_POST_TX_SETTLE_US = SX1262_POST_TX_SETTLE_US

staticconstexpr

LR1121-specific post-TX settling delay before re-entering RX.

Seeded from the SX1262-validated default; same rationale as LR1121_RESPONSE_PREAMBLE.

Definition at line 151 of file tuning_config.h.

LR1121_PREAMBLE_DETECTOR_16_BIT

uint8_t esphome::home_io_control::LR1121_PREAMBLE_DETECTOR_16_BIT = 0x05

staticconstexpr

Preamble detector length selector: 16 bits.

Shares the SX126x GFSK preamble-detector enum (0x00 off, 0x04=8bit, 0x05=16bit, 0x06=24bit, 0x07=32bit) — the LR11xx sub-GHz GFSK modem descends from the same core.

Definition at line 146 of file radio_lr1121.h.

LR1121_REG_GFSK_WORKAROUND_1_ADDR

uint32_t esphome::home_io_control::LR1121_REG_GFSK_WORKAROUND_1_ADDR = 0x00F20344

staticconstexpr

GFSK modulation workaround register trio, standard (non-0.6/1.2kbps) values for our 38.4kbps config — applied after every modulation-params write, mirroring RadioLib's workaroundGFSK() ("always the first step, even when resetting" per its own comment on the first write).

Definition at line 187 of file radio_lr1121.h.

LR1121_REG_GFSK_WORKAROUND_1_MASK

uint32_t esphome::home_io_control::LR1121_REG_GFSK_WORKAROUND_1_MASK = 0x00000030

staticconstexpr

Definition at line 188 of file radio_lr1121.h.

LR1121_REG_GFSK_WORKAROUND_1_VALUE

uint32_t esphome::home_io_control::LR1121_REG_GFSK_WORKAROUND_1_VALUE = 0x00000010

staticconstexpr

Definition at line 189 of file radio_lr1121.h.

LR1121_REG_GFSK_WORKAROUND_2_ADDR

uint32_t esphome::home_io_control::LR1121_REG_GFSK_WORKAROUND_2_ADDR = 0x00F20348

staticconstexpr

Definition at line 190 of file radio_lr1121.h.

LR1121_REG_GFSK_WORKAROUND_2_MASK

uint32_t esphome::home_io_control::LR1121_REG_GFSK_WORKAROUND_2_MASK = 0x00000005

staticconstexpr

Definition at line 191 of file radio_lr1121.h.

LR1121_REG_GFSK_WORKAROUND_2_VALUE

uint32_t esphome::home_io_control::LR1121_REG_GFSK_WORKAROUND_2_VALUE = 0x00000001

staticconstexpr

Definition at line 192 of file radio_lr1121.h.

LR1121_REG_GFSK_WORKAROUND_3_ADDR

uint32_t esphome::home_io_control::LR1121_REG_GFSK_WORKAROUND_3_ADDR = 0x00F20244

staticconstexpr

Definition at line 193 of file radio_lr1121.h.

LR1121_REG_GFSK_WORKAROUND_3_MASK

uint32_t esphome::home_io_control::LR1121_REG_GFSK_WORKAROUND_3_MASK = 0x0001FF03

staticconstexpr

Definition at line 194 of file radio_lr1121.h.

LR1121_REG_GFSK_WORKAROUND_3_VALUE

uint32_t esphome::home_io_control::LR1121_REG_GFSK_WORKAROUND_3_VALUE = 0x00000A01

staticconstexpr

Definition at line 195 of file radio_lr1121.h.

LR1121_REG_HIGH_ACP_WORKAROUND_ADDR

uint32_t esphome::home_io_control::LR1121_REG_HIGH_ACP_WORKAROUND_ADDR = 0x00F30054

staticconstexpr

High-ACP (adjacent channel power) TX-quality erratum: clear bit 30 of this register before every SetRx/SetTx.

Without it the chip's TX spectrum has excess spectral regrowth — plausibly why our own (tolerant) monitors decode our frames byte-exact while the awning's spec-compliant receiver mostly can't.

Definition at line 180 of file radio_lr1121.h.

LR1121_REG_HIGH_ACP_WORKAROUND_MASK

uint32_t esphome::home_io_control::LR1121_REG_HIGH_ACP_WORKAROUND_MASK = 1UL << 30

staticconstexpr

Definition at line 181 of file radio_lr1121.h.

LR1121_REG_HIGH_ACP_WORKAROUND_VALUE

uint32_t esphome::home_io_control::LR1121_REG_HIGH_ACP_WORKAROUND_VALUE = 0x00000000

staticconstexpr

Definition at line 182 of file radio_lr1121.h.

LR1121_RESPONSE_PREAMBLE

uint16_t esphome::home_io_control::LR1121_RESPONSE_PREAMBLE = SX1262_RESPONSE_PREAMBLE

staticconstexpr

LR1121-specific preamble for response/continuation frames within an exchange.

Seeded from the SX1262-validated default, on the principle that a validated timing value encodes protocol-side reality more than a chip quirk. Not yet independently validated on LR1121 hardware; a value measured by loopback tuning would fold back here.

Definition at line 146 of file tuning_config.h.

LR1121_RFSWITCH_ENABLE_DIO5_DIO6

uint8_t esphome::home_io_control::LR1121_RFSWITCH_ENABLE_DIO5_DIO6 = 0x03

staticconstexpr

DIO5 + DIO6 are switch pins.

Definition at line 211 of file radio_lr1121.h.

LR1121_RFSWITCH_GNSS

uint8_t esphome::home_io_control::LR1121_RFSWITCH_GNSS = 0x00

staticconstexpr

Unused; both low.

Definition at line 217 of file radio_lr1121.h.

LR1121_RFSWITCH_RX

uint8_t esphome::home_io_control::LR1121_RFSWITCH_RX = 0x01

staticconstexpr

DIO5 high.

Definition at line 213 of file radio_lr1121.h.

LR1121_RFSWITCH_STANDBY

uint8_t esphome::home_io_control::LR1121_RFSWITCH_STANDBY = 0x00

staticconstexpr

Both low.

Definition at line 212 of file radio_lr1121.h.

LR1121_RFSWITCH_TX

uint8_t esphome::home_io_control::LR1121_RFSWITCH_TX = 0x02

staticconstexpr

DIO6 high (both LP and HP PA).

Definition at line 214 of file radio_lr1121.h.

LR1121_RFSWITCH_TX_HF

uint8_t esphome::home_io_control::LR1121_RFSWITCH_TX_HF = 0x00

staticconstexpr

2.4GHz path unused; both low.

Definition at line 216 of file radio_lr1121.h.

LR1121_RFSWITCH_TX_HP

uint8_t esphome::home_io_control::LR1121_RFSWITCH_TX_HP = 0x02

staticconstexpr

Same as TX (LP PA only used today).

Definition at line 215 of file radio_lr1121.h.

LR1121_RFSWITCH_WIFI

uint8_t esphome::home_io_control::LR1121_RFSWITCH_WIFI = 0x00

staticconstexpr

Unused; both low.

Definition at line 218 of file radio_lr1121.h.

LR1121_RX_BUFFER_BASE

uint8_t esphome::home_io_control::LR1121_RX_BUFFER_BASE = 0x00

staticconstexpr

Offset a reception is written to in the LR1121's data buffer.

Unlike the SX1262 there is no SetBufferBaseAddress on this chip — the whole 256-byte buffer is one area whose pointers the chip manages, and a fresh reception after SetRx starts at the bottom of it (the same buffer model RadioLR1121::write_buffer_'s own doc comment records for the TX direction). Used as the read offset for the length-driven receive; see RadioLR1121::early_rx_read_offset.

Definition at line 168 of file radio_lr1121.h.

LR1121_SYNC_WORD_PARAM_24_BITS

uint8_t esphome::home_io_control::LR1121_SYNC_WORD_PARAM_24_BITS = 0x18

staticconstexpr

Sync word length: 24 bits, encoded as a literal bit count — cross-checked, identical encoding to SX1262's SX1262_SYNC_WORD_PARAM_24_BITS.

Definition at line 149 of file radio_lr1121.h.

LR1121_TCXO_STARTUP_DELAY_TICKS_LSB

uint8_t esphome::home_io_control::LR1121_TCXO_STARTUP_DELAY_TICKS_LSB = 0x40

staticconstexpr

0x140 ticks at 30.52us/tick (32.768kHz RTC) is ~9.8ms (the SX1262's tick base differs, so the same tick count means a different time there) — harmless either way, since a longer startup is safe.

Definition at line 235 of file radio_lr1121.h.

LR1121_TCXO_STARTUP_DELAY_TICKS_MID

uint8_t esphome::home_io_control::LR1121_TCXO_STARTUP_DELAY_TICKS_MID = 0x01

staticconstexpr

Definition at line 232 of file radio_lr1121.h.

LR1121_TCXO_STARTUP_DELAY_TICKS_MSB

uint8_t esphome::home_io_control::LR1121_TCXO_STARTUP_DELAY_TICKS_MSB = 0x00

staticconstexpr

LR1121 TCXO voltage on the T3-S3 board — 3.0V, confirmed on real hardware.

Definition at line 231 of file radio_lr1121.h.

MANUFACTURER_ASSA_ABLOY

uint8_t esphome::home_io_control::MANUFACTURER_ASSA_ABLOY = 5

staticconstexpr

ASSA ABLOY (locks, access).

Definition at line 424 of file proto_constants.h.

MANUFACTURER_ATLANTIC_GROUP

uint8_t esphome::home_io_control::MANUFACTURER_ATLANTIC_GROUP = 12

staticconstexpr

Atlantic Group (heating, hot water).

Definition at line 431 of file proto_constants.h.

MANUFACTURER_CIAT

uint8_t esphome::home_io_control::MANUFACTURER_CIAT = 9

staticconstexpr

CIAT (HVAC).

Definition at line 428 of file proto_constants.h.

MANUFACTURER_HONEYWELL

uint8_t esphome::home_io_control::MANUFACTURER_HONEYWELL = 3

staticconstexpr

Honeywell.

Definition at line 422 of file proto_constants.h.

MANUFACTURER_HORMANN

uint8_t esphome::home_io_control::MANUFACTURER_HORMANN = 4

staticconstexpr

Hörmann (garage doors, gates).

Definition at line 423 of file proto_constants.h.

MANUFACTURER_ID_MAX

uint8_t esphome::home_io_control::MANUFACTURER_ID_MAX = 12

staticconstexpr

Maximum manufacturer ID with a known name in the lookup table.

Definition at line 413 of file proto_constants.h.

MANUFACTURER_NIKO

uint8_t esphome::home_io_control::MANUFACTURER_NIKO = 6

staticconstexpr

Niko (switches, home automation).

Definition at line 425 of file proto_constants.h.

MANUFACTURER_OVERKIZ

uint8_t esphome::home_io_control::MANUFACTURER_OVERKIZ = 11

staticconstexpr

OVERKIZ (Somfy connectivity platform).

Definition at line 430 of file proto_constants.h.

MANUFACTURER_RENSON

uint8_t esphome::home_io_control::MANUFACTURER_RENSON = 8

staticconstexpr

Renson (ventilation, sun protection).

Definition at line 427 of file proto_constants.h.

MANUFACTURER_SECUYOU

uint8_t esphome::home_io_control::MANUFACTURER_SECUYOU = 10

staticconstexpr

Secuyou (security).

Definition at line 429 of file proto_constants.h.

MANUFACTURER_SOMFY

uint8_t esphome::home_io_control::MANUFACTURER_SOMFY = 2

staticconstexpr

Somfy (shutters, awnings, blinds).

Definition at line 421 of file proto_constants.h.

MANUFACTURER_VELUX

uint8_t esphome::home_io_control::MANUFACTURER_VELUX = 1

staticconstexpr

IO-Homecontrol manufacturer ID constants.

These 1-based identifiers are assigned by the IO-Homecontrol alliance and appear in the discovery response payload at DISCOVERY_RESP_MANUFACTURER_OFFSET. VELUX (roof windows, skylights).

Definition at line 420 of file proto_constants.h.

MANUFACTURER_WINDOW_MASTER

uint8_t esphome::home_io_control::MANUFACTURER_WINDOW_MASTER = 7

staticconstexpr

WINDOW MASTER (ventilation).

Definition at line 426 of file proto_constants.h.

MAX_TRACKED_STATUS_POLL_WINDOW_MS

uint32_t esphome::home_io_control::MAX_TRACKED_STATUS_POLL_WINDOW_MS = 600000

staticconstexpr

Hard stop for bounded follow-up polling after a command or remote activity.

Definition at line 37 of file status_poll_policy.h.

MODE_MASK

uint8_t esphome::home_io_control::MODE_MASK = 0x07

staticconstexpr

Definition at line 63 of file radio_sx1276.h.

MODE_RX

uint8_t esphome::home_io_control::MODE_RX = 0x05

staticconstexpr

Definition at line 62 of file radio_sx1276.h.

MODE_SLEEP

uint8_t esphome::home_io_control::MODE_SLEEP = 0x00

staticconstexpr

Definition at line 59 of file radio_sx1276.h.

MODE_STDBY

uint8_t esphome::home_io_control::MODE_STDBY = 0x01

staticconstexpr

Definition at line 60 of file radio_sx1276.h.

MODE_TX

uint8_t esphome::home_io_control::MODE_TX = 0x03

staticconstexpr

Definition at line 61 of file radio_sx1276.h.

NODE_ID_SIZE

uint8_t esphome::home_io_control::NODE_ID_SIZE = 3

staticconstexpr

Device/node addresses are 3 bytes (e.g., "123ABC").

Definition at line 20 of file proto_sizes.h.

NODE_ID_STRING_SIZE

uint8_t esphome::home_io_control::NODE_ID_STRING_SIZE = (NODE_ID_SIZE * 2) + 1

staticconstexpr

Uppercase hex node ID plus null terminator.

Definition at line 21 of file proto_sizes.h.

NORMAL_START_PREAMBLE

uint16_t esphome::home_io_control::NORMAL_START_PREAMBLE = 32

staticconstexpr

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).

An always-listening receiver does not need the ~213 ms LONG_PREAMBLE wake-up burst, and some receivers never lock onto one that long; a normal start frame gets this shorter preamble instead, matching what a reference hub sends to an always-alive device.

32 bytes = 256 bits sits inside the preamble band the iown-homecontrol documentation describes (256 bits in its radio notes; 128 bits is the "Long PPDU" preamble in its link-layer notes), well above the ~12-byte response preamble a short-turnaround chip uses, ~6.7 ms of air time, and two orders of magnitude below the 1024-byte burst. 8 bytes is a proven lower bound against paired always-alive devices but nothing bounds where a start frame stops being heard, so 32 is the defensible middle — and normal_start_preamble is a live tuning knob so a wrong guess costs a number change, not a rebuild.

Definition at line 62 of file proto_timing.h.

NUMBER_PARAMS

TuningNumberParam esphome::home_io_control::NUMBER_PARAMS[]

staticconstexpr

Definition at line 23 of file tuning_registry.cpp.

ONEWAY_BURST_INTERVAL_MS

uint32_t esphome::home_io_control::ONEWAY_BURST_INTERVAL_MS = 40

staticconstexpr

Gap between those copies.

Three gaps between four copies is 3 * 40 = 120 ms of pure delay; adding each of the four copies' own airtime brings the wall-clock burst closer to ~160 ms. send_burst()'s doxygen (oneway_transmitter.h) states both — they are not competing claims about the same number, just two different things measured on the same burst.

Definition at line 189 of file proto_timing.h.

ONEWAY_BURST_REPEATS

uint8_t esphome::home_io_control::ONEWAY_BURST_REPEATS = 4

staticconstexpr

One-way (1W) transmit cadence.

A 1W command is fire-and-forget: nothing replies, so there is no acknowledgement to retry on and no way to learn a frame was missed. Repetition is the reliability mechanism — real remotes send the same frame four times, and a receiving device treats the set as one command because all four carry the same sequence. These are protocol values shared by every 1W transmitter, not radio tuning: they do not vary by chip and must not be moved into a driver or a TuningConfig field.

Both values come from the reference implementation, which sets them on adjacent lines when it forges a 1W packet: packet->repeat = 4 and packet->repeatTime = 40 in its 1W remote. The capture logs embedded in that same source show consecutive copies of one burst arriving roughly 25 ms apart, which is not a contradiction: those are receive-side timestamps of a burst whose configured gap is 40 ms, so they measure something else. Do not "correct" 40 down to 25 on the strength of them.

Erring long would in any case be the safe direction — a device needs only one of the four copies to land, so a wider spacing costs nothing and leaves more room on a shared band.

The resulting burst duration — see ONEWAY_BURST_INTERVAL_MS's own comment and send_burst()'s doxygen (oneway_transmitter.h) for the two numbers this decomposes into — is what ONEWAY_QUIET_PERIOD_MS (status_poll_policy.h) is sized against when it holds background polls back during 1W activity. Copies of each 1W command sent per press.

Definition at line 184 of file proto_timing.h.

ONEWAY_EXECUTE_ACEI

uint8_t esphome::home_io_control::ONEWAY_EXECUTE_ACEI

staticconstexpr

Initial value:

                                         =
(ACEI_LEVEL_USER_HIGH << ACEI_LEVEL_SHIFT) | (1 << ACEI_EXTENDED_SHIFT) | ACEI_VALID_BIT

ACEI byte for a 1W CMD_EXECUTE frame — the Somfy-shaped default.

Level 2 (user_high), extended-info bit set. The 2W EXECUTE_ACEI (proto_commands.cpp) pins level 3 to a real captured 2W hub; this level-2 value is what the published 1W reference vector (tests/corpus/captures/oneway/reference_1w_oneway_execute_iv_vector.yaml) and every Somfy 1W remote frame in the corpus (7+ frames across 3 nodes: 9D6085, 485B37, 7B8240) carry. Lives here (not proto_commands.cpp) so oneway_controller.h's resolve_oneway_wire_profile() can name it without the protocol layer depending on the controller layer. Composition: (ACEI_LEVEL_USER_HIGH << 5) | (1 << 1) | 1 = 0x43.

Definition at line 543 of file proto_constants.h.

ONEWAY_EXECUTE_ACEI_VELUX

uint8_t esphome::home_io_control::ONEWAY_EXECUTE_ACEI_VELUX = (ACEI_LEVEL_USER_DEFAULT << ACEI_LEVEL_SHIFT) | ACEI_VALID_BIT

staticconstexpr

ACEI byte for a 1W CMD_EXECUTE frame from a VELUX KLI-class remote.

Level 3 (user_default), extended-info bits clear. This is also iown-homecontrol's generic ACEI_DEFAULT. Confidence: n=1 — one corpus frame (tests/corpus/captures/oneway/velux_kli313_oneway_stop.yaml) plus samr037/iohc-flipper's README, which names cmd 0x00 payload[1] the "vendor byte" (0x43 Somfy / 0x61 Velux). The unidentified_1w_remote_* frames also carry 0x61 but their manufacturer is unknown, so they can't corroborate the VELUX attribution. execute_acei: on the identity is the escape hatch. Composition: (ACEI_LEVEL_USER_DEFAULT << 5) | ACEI_VALID_BIT = 0x61.

Definition at line 555 of file proto_constants.h.

ONEWAY_EXECUTE_MIN_DATA_LEN

uint8_t esphome::home_io_control::ONEWAY_EXECUTE_MIN_DATA_LEN = 4

staticconstexpr

Minimum data bytes for decode of execute/activate‑mode intent fields.

Definition at line 329 of file proto_codecs.cpp.

ONEWAY_INTENT_BUFFER_SIZE

size_t esphome::home_io_control::ONEWAY_INTENT_BUFFER_SIZE = 24

staticconstexpr

Buffer size for the decoded 1W main-intent string.

Definition at line 168 of file proto_codecs.h.

ONEWAY_POLL_DEFER_CAP_MS

uint32_t esphome::home_io_control::ONEWAY_POLL_DEFER_CAP_MS = 5000

staticconstexpr

Hard cap on how long sustained 1W traffic may hold a background poll back in total, measured from the start of the burst rather than the most recent frame.

ONEWAY_QUIET_PERIOD_MS re-arms on every frame, so without this cap traffic arriving faster than the quiet period apart — a stuck remote, a chatty neighbour's sensor — could starve background polls, and therefore device state freshness, indefinitely. Comfortably above a legitimate ~160ms burst; bounds the worst case without meaningfully affecting normal operation.

Definition at line 53 of file status_poll_policy.h.

ONEWAY_POSITION_FULLY_CLOSED

uint8_t esphome::home_io_control::ONEWAY_POSITION_FULLY_CLOSED = 100

staticconstexpr

Definition at line 158 of file oneway_controller.h.

ONEWAY_POSITION_FULLY_OPEN

uint8_t esphome::home_io_control::ONEWAY_POSITION_FULLY_OPEN = 0

staticconstexpr

Wire-scale position meaning "fully closed" (0 means fully open).

Named here because the two values are what OPEN and CLOSE actually are — see encode_oneway_action().

Definition at line 157 of file oneway_controller.h.

ONEWAY_QUIET_PERIOD_MS

uint32_t esphome::home_io_control::ONEWAY_QUIET_PERIOD_MS = 700

staticconstexpr

Hold queued background polls back for this long after any 1W frame, so a poll the hub itself scheduled does not occupy the (half-duplex) radio while the remote is still transmitting.

Comfortably longer than the ~160ms reliability burst; short enough to barely shift poll timing otherwise. Only background polls yield — see decisions::defer_background_poll_for_1w_activity().

Definition at line 46 of file status_poll_policy.h.

ONEWAY_SEQUENCE_ACCEPTANCE_WINDOW

uint16_t esphome::home_io_control::ONEWAY_SEQUENCE_ACCEPTANCE_WINDOW = 1000

staticconstexpr

How far ahead of its stored high-water mark a device will still accept a jump.

1000 is the window the iohomecontrol reference receiver applies, and it is the ceiling every forward skip in this file has to stay under: a jump past it fails exactly like a stale counter, and just as silently.

Definition at line 41 of file oneway_sequence_store.h.

ONEWAY_SEQUENCE_REBOOT_HEADROOM

uint16_t esphome::home_io_control::ONEWAY_SEQUENCE_REBOOT_HEADROOM = 8

staticconstexpr

How many consecutive unclean reboots the stride must survive while staying inside a device's acceptance window.

Eight is far past plausible; the point is headroom, not precision.

Definition at line 53 of file oneway_sequence_store.h.

ONEWAY_SEQUENCE_STRIDE

uint16_t esphome::home_io_control::ONEWAY_SEQUENCE_STRIDE = 8

staticconstexpr

How many sequences one flash write reserves.

Persisting on every command would write flash on every button press. Reserving a block instead trades that for a bounded forward skip: an unclean reboot forfeits the block's unused remainder, which is the safe direction. Small on purpose — see the static_assert below for the bound, and raise it only if that bound still holds.

Definition at line 49 of file oneway_sequence_store.h.

ORIGINATOR_AUTOMATIC_CYCLE

uint8_t esphome::home_io_control::ORIGINATOR_AUTOMATIC_CYCLE = 0xFE

staticconstexpr

Automatic cycle / external access.

Definition at line 482 of file proto_constants.h.

ORIGINATOR_EMERGENCY

uint8_t esphome::home_io_control::ORIGINATOR_EMERGENCY = 0xFF

staticconstexpr

Emergency command (never disabled).

Definition at line 483 of file proto_constants.h.

ORIGINATOR_ENVIRONMENT

uint8_t esphome::home_io_control::ORIGINATOR_ENVIRONMENT = 0x0D

staticconstexpr

Unspecified environment sensor.

Definition at line 480 of file proto_constants.h.

ORIGINATOR_LIFESTYLE

uint8_t esphome::home_io_control::ORIGINATOR_LIFESTYLE = 0x07

staticconstexpr

Lifestyle scenario controller.

Definition at line 475 of file proto_constants.h.

ORIGINATOR_LOAD_SHEDDING

uint8_t esphome::home_io_control::ORIGINATOR_LOAD_SHEDDING = 0x0B

staticconstexpr

Load-shedding manager.

Definition at line 478 of file proto_constants.h.

ORIGINATOR_LOCAL_LIGHT

uint8_t esphome::home_io_control::ORIGINATOR_LOCAL_LIGHT = 0x0C

staticconstexpr

Local light sensor.

Definition at line 479 of file proto_constants.h.

ORIGINATOR_LOCAL_USER

uint8_t esphome::home_io_control::ORIGINATOR_LOCAL_USER = 0x00

staticconstexpr

Command originator codes indicating what or who triggered a command.

The originator byte is the first byte of the CMD_EXECUTE payload. It tells the actuator (and any eavesdropping controller) who initiated the movement. This is useful for understanding device-initiated status updates.

ORIGINATOR_WIND_SENSOR and ORIGINATOR_RAIN_SENSOR are both field-confirmed on real hardware — a single combined wind/rain protection station (issue #27, community capture) broadcasting both values minutes apart: tests/corpus/captures/oneway/wind_sensor_oneway_favorite_wind_originator_sx1276.yaml and tests/corpus/captures/oneway/wind_sensor_oneway_favorite_rain_originator_sx1276.yaml. The latter is this project's first real-hardware confirmation of ORIGINATOR_RAIN_SENSOR at all — every prior wind/rain-station capture used ORIGINATOR_WIND_SENSOR only. User pressed a button on the actuator.

Definition at line 468 of file proto_constants.h.

ORIGINATOR_MYSELF

uint8_t esphome::home_io_control::ORIGINATOR_MYSELF = 0x10

staticconstexpr

Actuator decided to move by itself.

Definition at line 481 of file proto_constants.h.

ORIGINATOR_RAIN_SENSOR

uint8_t esphome::home_io_control::ORIGINATOR_RAIN_SENSOR = 0x02

staticconstexpr

Rain sensor triggered the movement.

Definition at line 470 of file proto_constants.h.

ORIGINATOR_SAAC

uint8_t esphome::home_io_control::ORIGINATOR_SAAC = 0x08

staticconstexpr

Stand-alone automatic controller (SAAC).

Definition at line 476 of file proto_constants.h.

ORIGINATOR_SECURITY

uint8_t esphome::home_io_control::ORIGINATOR_SECURITY = 0x04

staticconstexpr

Security controlling device (SCD) action.

Definition at line 472 of file proto_constants.h.

ORIGINATOR_SMART_CONTROLLER

uint8_t esphome::home_io_control::ORIGINATOR_SMART_CONTROLLER = 0x06

staticconstexpr

Smart function controller.

Definition at line 474 of file proto_constants.h.

ORIGINATOR_TIMER

uint8_t esphome::home_io_control::ORIGINATOR_TIMER = 0x03

staticconstexpr

Timer or schedule triggered the movement.

Definition at line 471 of file proto_constants.h.

ORIGINATOR_UPS

uint8_t esphome::home_io_control::ORIGINATOR_UPS = 0x05

staticconstexpr

Uninterruptible power supply action.

Definition at line 473 of file proto_constants.h.

ORIGINATOR_USER_REMOTE

uint8_t esphome::home_io_control::ORIGINATOR_USER_REMOTE = 0x01

staticconstexpr

User sent command from a remote control.

Definition at line 469 of file proto_constants.h.

ORIGINATOR_WIND_SENSOR

uint8_t esphome::home_io_control::ORIGINATOR_WIND_SENSOR = 0x09

staticconstexpr

Wind sensor triggered the movement.

Definition at line 477 of file proto_constants.h.

PAIRING_DISCOVERY_INITIAL_DWELL_MS

uint16_t esphome::home_io_control::PAIRING_DISCOVERY_INITIAL_DWELL_MS = 300

staticconstexpr

Dwell on CH2 before discovery hopping begins.

Definition at line 207 of file proto_timing.h.

PAIRING_DISCOVERY_MAX_ATTEMPTS

uint8_t esphome::home_io_control::PAIRING_DISCOVERY_MAX_ATTEMPTS = 3

inlineconstexpr

Retry discovery TX up to this many times.

Definition at line 50 of file pairing_engine.h.

PAIRING_DISCOVERY_PREAMBLE

uint16_t esphome::home_io_control::PAIRING_DISCOVERY_PREAMBLE = LONG_PREAMBLE

staticconstexpr

Default for TuningConfig::pairing_discovery_preamble — the preamble on the pairing discovery broadcast (CMD_DISCOVER_REQ/CMD_DISCOVER_ALT_REQ, 0x28/0x2E).

Defaults to LONG_PREAMBLE, unchanged from historical behavior: a factory-fresh device in learning mode is exactly the kind of duty-cycled receiver LONG_PREAMBLE exists to wake. But unlike every other directed start frame (see NORMAL_START_PREAMBLE's history, issue #87 — some always-alive receivers never lock onto a preamble this long), the discovery broadcast can't be made power-class-aware the same way: discovery exists to learn a device before anything is known about it, so it still unconditionally pays LONG_PREAMBLE's ~213 ms even against an always-listening target. Issue #27 (Somfy Sunea IO devices repeatedly failing to answer discovery) raised this as a plausible, unconfirmed contributor. Runtime-tunable via pairing_discovery_preamble so that hypothesis is testable without a rebuild — not yet hardware-confirmed as a fix for any specific device.

Definition at line 75 of file proto_timing.h.

PAIRING_DISCOVERY_RESPONSE_TIMEOUT_MS

uint32_t esphome::home_io_control::PAIRING_DISCOVERY_RESPONSE_TIMEOUT_MS = 2000

inlineconstexpr

Discovery wait window after sending 0x28.

Definition at line 49 of file pairing_engine.h.

PAIRING_DISCOVERY_WAIT_MS

uint16_t esphome::home_io_control::PAIRING_DISCOVERY_WAIT_MS = 2000

staticconstexpr

Canonical defaults for the chip-neutral runtime-tunable pairing/discovery parameters.

These are the single source of truth for the diagnostics tuning layer: TuningConfig initializes its fields from them, and the ESPHome YAML schema falls back to them when a key is omitted. Adjust a value here and both the compiled default and the documented YAML default follow. Chip-specific tuning defaults live in tuning_config.h instead. See Pairing/Radio Diagnostics Tuning. Wait window after sending each discovery command.

Definition at line 206 of file proto_timing.h.

PAIRING_KEY_CHALLENGE_TIMEOUT_MS

uint32_t esphome::home_io_control::PAIRING_KEY_CHALLENGE_TIMEOUT_MS = 500

inlineconstexpr

Wait window for the device's 0x3C challenge.

Definition at line 51 of file pairing_engine.h.

PAIRING_KEY_CONFIRM_TIMEOUT_MS

uint32_t esphome::home_io_control::PAIRING_KEY_CONFIRM_TIMEOUT_MS = 500

inlineconstexpr

Wait for 0x33 key confirm after sending 0x32.

Definition at line 52 of file pairing_engine.h.

PAIRING_KEY_EXCHANGE_RETRIES

uint8_t esphome::home_io_control::PAIRING_KEY_EXCHANGE_RETRIES = 3

staticconstexpr

Retries for the authenticated key-exchange phase.

Definition at line 208 of file proto_timing.h.

PAIRING_RECENT_ONE_WAY_SIGHTING_WINDOW_MS

uint32_t esphome::home_io_control::PAIRING_RECENT_ONE_WAY_SIGHTING_WINDOW_MS = 15000

inlineconstexpr

How recent a RecentOneWayPairingSighting has to be, relative to discover_and_pair() starting, to still count as evidence for this attempt.

Generous relative to the doc's "a few seconds" PROG-then-press guidance: real field reports (issue #27) show gaps up to ~4-7 s between the PROG gesture and pressing "Discover & Pair" in the app, so a tight window would reintroduce the same miss it's meant to fix. Not tied to ONEWAY_QUIET_PERIOD_MS (status_poll_policy.h, 700 ms) — that constant is about collapsing one remote's repeat burst, a different, much shorter timescale than "how long ago did the user press PROG."

Definition at line 60 of file pairing_engine.h.

PAIRING_TELEMETRY_MAX_EVENTS

uint8_t esphome::home_io_control::PAIRING_TELEMETRY_MAX_EVENTS = 32

staticconstexpr

Maximum number of events recorded per pairing attempt.

Events beyond this bound are still counted in PairingTelemetry::heard_count() but not stored — the array is a fixed-size ring-free buffer (first N events), not a true ring.

Definition at line 43 of file pairing_telemetry.h.

POS_DEFAULT

uint8_t esphome::home_io_control::POS_DEFAULT = 0xD3

staticconstexpr

Wire value for the default position command.

Moves the actuator to its factory or user-configured default position.

Definition at line 328 of file proto_constants.h.

POS_FAVORITE

uint8_t esphome::home_io_control::POS_FAVORITE = 0xD8

staticconstexpr

Wire value: move to favorite/"My" position.

Definition at line 316 of file proto_constants.h.

POS_FORCE_OPEN

uint8_t esphome::home_io_control::POS_FORCE_OPEN = 0x64

staticconstexpr

Ambiguous wire value used only for passive 1W-traffic intent decoding (decode_1w_main_intent() / oneway_intent_to_target() in proto_codecs.cpp).

0x64 (100) is simultaneously the ordinary doubled-position wire value for 50% and a value some physical 1W remotes send for their "force open" button — the protocol has no dedicated override code, so the two are indistinguishable on the wire. For passively decoding someone else's remote traffic, "FORCE_OPEN" is the more useful diagnostic label (physical remotes rarely send a numeric 50%). This is NOT used by any outbound builder in this codebase: real-hardware testing confirmed that sending main=0x64 as an outbound 2W CMD_EXECUTE command makes a real device move to 50% open, not bypass anything — see create_force_open() in proto_commands.cpp for the actual (ACEI-priority-based) force-open implementation.

Definition at line 342 of file proto_constants.h.

POS_SECURED_TARGET

uint8_t esphome::home_io_control::POS_SECURED_TARGET = 0xD1

staticconstexpr

Wire value for the secured target position command.

Moves the actuator to its pre-programmed secured/safety position from the Execution Parameter Buffer. Typically sent by environmental sensors (wind, rain) to retract an awning or close a shutter to a wind-safe state.

Definition at line 323 of file proto_constants.h.

POS_STOP

uint8_t esphome::home_io_control::POS_STOP = 0xD2

staticconstexpr

Position values in the IO protocol.

Normal positions are 0-100 (0=fully open, 100=fully closed). Special values above 100 are control commands encoded as the "main" parameter byte in CMD_EXECUTE payloads. These are internal wire constants — callers should prefer CoverCommand for type-safe command dispatch. Wire value: stop movement.

Definition at line 314 of file proto_constants.h.

POS_UNKNOWN

uint8_t esphome::home_io_control::POS_UNKNOWN = 0xD4

staticconstexpr

Wire value: position unknown / keep current.

Definition at line 315 of file proto_constants.h.

POS_VENT_MODIFIER

uint8_t esphome::home_io_control::POS_VENT_MODIFIER = 0x03

staticconstexpr

Modifier byte for the ventilation command.

Both favorite and ventilation use POS_FAVORITE (0xD8) as the main parameter byte, but ventilation sets the secondary byte (main[1]) to 0x03 while favorite leaves it 0x00.

Definition at line 348 of file proto_constants.h.

POSITION_TEXT_BUFFER_SIZE

size_t esphome::home_io_control::POSITION_TEXT_BUFFER_SIZE = 16

inlineconstexpr

Buffer for formatted position strings such as "100%".

Definition at line 64 of file hub_core.h.

POSITION_WIRE_MAX

uint8_t esphome::home_io_control::POSITION_WIRE_MAX = 200

staticconstexpr

Highest doubled-position wire value: 100% * POSITION_WIRE_SCALE.

A main byte at or below this is an ordinary position; above it, one of the POS_* special codes.

Definition at line 359 of file proto_constants.h.

POSITION_WIRE_SCALE

uint8_t esphome::home_io_control::POSITION_WIRE_SCALE = 2

staticconstexpr

Scale factor between a 0-100 percent position and its CMD_EXECUTE main-byte wire value.

Percent 0-100 maps to wire 0-200 (wire = percent * POSITION_WIRE_SCALE), leaving 201-255 free for the POS_* special codes above. Builders multiply by this to encode a position; decoders divide by it to recover one — both directions belong on this one constant so they cannot silently drift apart into two different bare "2"s.

Definition at line 356 of file proto_constants.h.

POWER_SAVE_ALWAYS_ALIVE

uint8_t esphome::home_io_control::POWER_SAVE_ALWAYS_ALIVE = 0

staticconstexpr

Power save mode values from the Multi Information Byte.

Extracted from flags & DISCOVERY_FLAGS_POWER_SAVE_MASK. Devices in low-power mode require long preamble (1024 bytes) to wake their receiver. Device is always listening — short preamble works.

Definition at line 613 of file proto_constants.h.

POWER_SAVE_LOW_POWER

uint8_t esphome::home_io_control::POWER_SAVE_LOW_POWER = 1

staticconstexpr

Device sleeps — needs long preamble to wake.

Definition at line 614 of file proto_constants.h.

PREAMBLE_LINGER_DWELL_MS

uint32_t esphome::home_io_control::PREAMBLE_LINGER_DWELL_MS = 15

staticconstexpr

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.

Sized to a frame's air time, not to a hop slice, so it does not need to change when a chip's hop slice does. Shared by every rotating listen (pairing discovery, broadcast roll-call): both wait for the same class of short protocol frame, so there is no measured reason for them to differ.

Definition at line 83 of file proto_timing.h.

PRIVATE_GET_POSITION_STATUS

uint8_t esphome::home_io_control::PRIVATE_GET_POSITION_STATUS = 0x03

staticconstexpr

CMD_PRIVATE (0x03) function ID for a position-status request — data[0] of the payload.

The only function ID this codebase has ever captured on its own wire: it is what create_get_status() freezes create_private_function() at, and the default function_id of create_get_status_extended(). Lives here rather than in proto_commands.cpp because that default argument is spelled in proto_commands.h.

Definition at line 372 of file proto_constants.h.

RADIO_PACKET_BUFFER_SIZE

uint8_t esphome::home_io_control::RADIO_PACKET_BUFFER_SIZE

inlineconstexpr

Initial value:

                                              =
64

Scratch buffer size for raw radio packets and recovered frames.

Definition at line 22 of file radio_interface.h.

REG_AFC_BW

uint8_t esphome::home_io_control::REG_AFC_BW = 0x13

staticconstexpr

AFC bandwidth.

Definition at line 37 of file radio_sx1276.h.

REG_AFC_FEI

uint8_t esphome::home_io_control::REG_AFC_FEI = 0x1A

staticconstexpr

AFC auto clear.

Definition at line 38 of file radio_sx1276.h.

REG_BITRATE_LSB

uint8_t esphome::home_io_control::REG_BITRATE_LSB = 0x03

staticconstexpr

Definition at line 25 of file radio_sx1276.h.

REG_BITRATE_MSB

uint8_t esphome::home_io_control::REG_BITRATE_MSB = 0x02

staticconstexpr

Bit rate MSB = FXOSC / bitrate.

Definition at line 24 of file radio_sx1276.h.

REG_DIO_MAPPING1

uint8_t esphome::home_io_control::REG_DIO_MAPPING1 = 0x40

staticconstexpr

DIO0-DIO3 pin mapping.

Definition at line 52 of file radio_sx1276.h.

REG_DIO_MAPPING2

uint8_t esphome::home_io_control::REG_DIO_MAPPING2 = 0x41

staticconstexpr

DIO4-DIO5 pin mapping.

Definition at line 53 of file radio_sx1276.h.

REG_FDEV_LSB

uint8_t esphome::home_io_control::REG_FDEV_LSB = 0x05

staticconstexpr

Definition at line 27 of file radio_sx1276.h.

REG_FDEV_MSB

uint8_t esphome::home_io_control::REG_FDEV_MSB = 0x04

staticconstexpr

Frequency deviation MSB.

Definition at line 26 of file radio_sx1276.h.

REG_FIFO

uint8_t esphome::home_io_control::REG_FIFO = 0x00

staticconstexpr

FIFO read/write access.

Definition at line 22 of file radio_sx1276.h.

REG_FIFO_THRESH

uint8_t esphome::home_io_control::REG_FIFO_THRESH = 0x35

staticconstexpr

FIFO threshold for TX start condition.

Definition at line 49 of file radio_sx1276.h.

REG_FRF_LSB

uint8_t esphome::home_io_control::REG_FRF_LSB = 0x08

staticconstexpr

Definition at line 30 of file radio_sx1276.h.

REG_FRF_MID

uint8_t esphome::home_io_control::REG_FRF_MID = 0x07

staticconstexpr

Definition at line 29 of file radio_sx1276.h.

REG_FRF_MSB

uint8_t esphome::home_io_control::REG_FRF_MSB = 0x06

staticconstexpr

Carrier frequency MSB (freq = FRF * FXOSC / 2^19).

Definition at line 28 of file radio_sx1276.h.

REG_IMAGE_CAL

uint8_t esphome::home_io_control::REG_IMAGE_CAL = 0x3B

staticconstexpr

Image calibration.

Definition at line 56 of file radio_sx1276.h.

REG_IRQ_FLAGS1

uint8_t esphome::home_io_control::REG_IRQ_FLAGS1 = 0x3E

staticconstexpr

IRQ flags: mode ready, preamble detect, etc.

Definition at line 50 of file radio_sx1276.h.

REG_IRQ_FLAGS2

uint8_t esphome::home_io_control::REG_IRQ_FLAGS2 = 0x3F

staticconstexpr

IRQ flags: FIFO full/empty, payload ready, CRC ok.

Definition at line 51 of file radio_sx1276.h.

REG_LNA

uint8_t esphome::home_io_control::REG_LNA = 0x0C

staticconstexpr

Low noise amplifier gain and boost.

Definition at line 33 of file radio_sx1276.h.

REG_OP_MODE

uint8_t esphome::home_io_control::REG_OP_MODE = 0x01

staticconstexpr

Operating mode (sleep/standby/tx/rx).

Definition at line 23 of file radio_sx1276.h.

REG_OSC

uint8_t esphome::home_io_control::REG_OSC = 0x24

staticconstexpr

Oscillator / clock output.

Definition at line 40 of file radio_sx1276.h.

REG_PA_CONFIG

uint8_t esphome::home_io_control::REG_PA_CONFIG = 0x09

staticconstexpr

Power amplifier config (pin select + power level).

Definition at line 31 of file radio_sx1276.h.

REG_PA_RAMP

uint8_t esphome::home_io_control::REG_PA_RAMP = 0x0A

staticconstexpr

PA ramp time and modulation shaping.

Definition at line 32 of file radio_sx1276.h.

REG_PACKET_CONFIG1

uint8_t esphome::home_io_control::REG_PACKET_CONFIG1 = 0x30

staticconstexpr

Packet format, CRC, encoding.

Definition at line 46 of file radio_sx1276.h.

REG_PACKET_CONFIG2

uint8_t esphome::home_io_control::REG_PACKET_CONFIG2 = 0x31

staticconstexpr

Packet mode, IoHomeOn, PowerFrame.

Definition at line 47 of file radio_sx1276.h.

REG_PAYLOAD_LENGTH

uint8_t esphome::home_io_control::REG_PAYLOAD_LENGTH = 0x32

staticconstexpr

Max payload length.

Definition at line 48 of file radio_sx1276.h.

REG_PLLHOP

uint8_t esphome::home_io_control::REG_PLLHOP = 0x44

staticconstexpr

PLL hop: fast frequency change without standby.

Definition at line 55 of file radio_sx1276.h.

REG_PREAMBLE_DETECT

uint8_t esphome::home_io_control::REG_PREAMBLE_DETECT = 0x1F

staticconstexpr

Preamble detector config.

Definition at line 39 of file radio_sx1276.h.

REG_PREAMBLE_LSB

uint8_t esphome::home_io_control::REG_PREAMBLE_LSB = 0x26

staticconstexpr

Definition at line 43 of file radio_sx1276.h.

REG_PREAMBLE_MSB

uint8_t esphome::home_io_control::REG_PREAMBLE_MSB = 0x25

staticconstexpr

TX preamble length MSB.

Definition at line 42 of file radio_sx1276.h.

REG_RSSI_CONFIG

uint8_t esphome::home_io_control::REG_RSSI_CONFIG = 0x0E

staticconstexpr

RSSI smoothing.

Definition at line 35 of file radio_sx1276.h.

REG_RSSI_VALUE

uint8_t esphome::home_io_control::REG_RSSI_VALUE = 0x11

staticconstexpr

Instant RSSI value in FSK mode.

Definition at line 41 of file radio_sx1276.h.

REG_RX_BW

uint8_t esphome::home_io_control::REG_RX_BW = 0x12

staticconstexpr

Receiver bandwidth.

Definition at line 36 of file radio_sx1276.h.

REG_RX_CONFIG

uint8_t esphome::home_io_control::REG_RX_CONFIG = 0x0D

staticconstexpr

Receiver configuration (AFC, AGC, trigger).

Definition at line 34 of file radio_sx1276.h.

REG_SYNC_CONFIG

uint8_t esphome::home_io_control::REG_SYNC_CONFIG = 0x27

staticconstexpr

Sync word config (size, polarity, enable).

Definition at line 44 of file radio_sx1276.h.

REG_SYNC_VALUE1

uint8_t esphome::home_io_control::REG_SYNC_VALUE1 = 0x28

staticconstexpr

Sync word byte 1 (registers 0x28-0x2F for bytes 1-8).

Definition at line 45 of file radio_sx1276.h.

REG_VERSION

uint8_t esphome::home_io_control::REG_VERSION = 0x42

staticconstexpr

Chip version (should read 0x12 for SX1276).

Definition at line 54 of file radio_sx1276.h.

REMOTE_ACTIVITY_STATUS_POLL_DELAY_MS

uint32_t esphome::home_io_control::REMOTE_ACTIVITY_STATUS_POLL_DELAY_MS = 2000

staticconstexpr

Delay before polling after overheard remote traffic.

Definition at line 41 of file status_poll_policy.h.

RESPONSE_AUTH_WAIT_MS

int32_t esphome::home_io_control::RESPONSE_AUTH_WAIT_MS

staticconstexpr

Initial value:

                                           =
RESPONSE_WAIT_MS

Wait for final response after challenge response.

Definition at line 109 of file proto_timing.h.

RESPONSE_START_WAIT_MS

int32_t esphome::home_io_control::RESPONSE_START_WAIT_MS = 400

staticconstexpr

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.

This device class replies within a few milliseconds of the carrier dropping, or not at all — it is fast-or-never, not slow. A failure therefore shows up as saw_challenge=0 with no frame received at all, rather than as a late arrival, so a longer window cannot fix a device that genuinely fails to answer.

400 ms sits comfortably above every directly measured reply while keeping a failed exchange inside EXCHANGE_TOTAL_BUDGET_MS, so a dead device does not block the ESPHome loop past its own warning threshold (ADR 0013). Raise exchange_start_response_wait_ms from YAML if a device ever genuinely answers late — but check wait_ms in the logs first, since a fast-or-never device is a turnaround problem that a longer window cannot fix.

Definition at line 107 of file proto_timing.h.

RESPONSE_WAIT_MS

int32_t esphome::home_io_control::RESPONSE_WAIT_MS = 500

staticconstexpr

Wait for response to non-start frame.

Definition at line 92 of file proto_timing.h.

RESULT_AUTOMATIC_CYCLE_ENGAGED

uint8_t esphome::home_io_control::RESULT_AUTOMATIC_CYCLE_ENGAGED = 0x18

staticconstexpr

Node entered automatic cycle mode.

Definition at line 271 of file proto_constants.h.

RESULT_BAD_INDEX_RECEIVED

uint8_t esphome::home_io_control::RESULT_BAD_INDEX_RECEIVED = 0x1C

staticconstexpr

Invalid index received.

Definition at line 275 of file proto_constants.h.

RESULT_BATTERY_LEVEL

uint8_t esphome::home_io_control::RESULT_BATTERY_LEVEL = 0x12

staticconstexpr

Battery level is low.

Definition at line 265 of file proto_constants.h.

RESULT_BLOCKED

uint8_t esphome::home_io_control::RESULT_BLOCKED = 0x04

staticconstexpr

Node blocked by an object.

Definition at line 251 of file proto_constants.h.

RESULT_CALIBRATING

uint8_t esphome::home_io_control::RESULT_CALIBRATING = 0x0A

staticconstexpr

Node is calibrating.

Definition at line 257 of file proto_constants.h.

RESULT_COLOUR_NOT_REACHABLE

uint8_t esphome::home_io_control::RESULT_COLOUR_NOT_REACHABLE = 0x1A

staticconstexpr

Requested colour not reachable.

Definition at line 273 of file proto_constants.h.

RESULT_COMMAND_COMPLETED_OK

uint8_t esphome::home_io_control::RESULT_COMMAND_COMPLETED_OK = 0x01

staticconstexpr

No errors detected.

Definition at line 248 of file proto_constants.h.

RESULT_COMMAND_INCOMPATIBLE_TO_MOVEMENT

uint8_t esphome::home_io_control::RESULT_COMMAND_INCOMPATIBLE_TO_MOVEMENT = 0x15

staticconstexpr

Command cannot move the node that way.

Definition at line 268 of file proto_constants.h.

RESULT_COMMAND_OVERRULED

uint8_t esphome::home_io_control::RESULT_COMMAND_OVERRULED = 0x1D

staticconstexpr

Command was overruled by a newer command.

Definition at line 276 of file proto_constants.h.

RESULT_DEAD_BOLT_ERROR

uint8_t esphome::home_io_control::RESULT_DEAD_BOLT_ERROR = 0x17

staticconstexpr

Dead bolt error.

Definition at line 270 of file proto_constants.h.

RESULT_ERROR_DURING_EXECUTION

uint8_t esphome::home_io_control::RESULT_ERROR_DURING_EXECUTION = 0x08

staticconstexpr

Generic execution failure.

Definition at line 255 of file proto_constants.h.

RESULT_FILTER_MAINTENANCE_NEEDED

uint8_t esphome::home_io_control::RESULT_FILTER_MAINTENANCE_NEEDED = 0x11

staticconstexpr

Filter needs maintenance.

Definition at line 264 of file proto_constants.h.

RESULT_INFORMATION_CODE

uint8_t esphome::home_io_control::RESULT_INFORMATION_CODE = 0xDF

staticconstexpr

Information-only code with unknown semantics.

Definition at line 290 of file proto_constants.h.

RESULT_INVALID_FUNCTION_INDEX

uint8_t esphome::home_io_control::RESULT_INVALID_FUNCTION_INDEX

staticconstexpr

Initial value:

                                                   =
0x58

CMD_PRIVATE-family function ID / sub-index / selector-block outside the range the device implements.

Seen cross-vendor (Somfy Sunea awning + dimmer, Velux window) when a diagnostic probe walks past the last supported index; not in any reference error table. Distinct from RESULT_BAD_INDEX_RECEIVED (0x1C).

Definition at line 285 of file proto_constants.h.

RESULT_IP_NOT_SET

uint8_t esphome::home_io_control::RESULT_IP_NOT_SET = 0x23

staticconstexpr

Intermediate position is not set.

Definition at line 281 of file proto_constants.h.

RESULT_LIMITATION_BY_AUTOMATIC_CYCLE

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_AUTOMATIC_CYCLE = 0xED

staticconstexpr

Parameter limited by an automatic cycle.

Definition at line 302 of file proto_constants.h.

RESULT_LIMITATION_BY_EMERGENCY

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_EMERGENCY = 0xEE

staticconstexpr

Parameter limited by an emergency.

Definition at line 303 of file proto_constants.h.

RESULT_LIMITATION_BY_LOCAL_USER

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_LOCAL_USER = 0xE1

staticconstexpr

Parameter limited by local button.

Definition at line 292 of file proto_constants.h.

RESULT_LIMITATION_BY_MYSELF

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_MYSELF = 0xEC

staticconstexpr

Parameter limited by the node itself.

Definition at line 301 of file proto_constants.h.

RESULT_LIMITATION_BY_RAIN

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_RAIN = 0xE3

staticconstexpr

Parameter limited by a rain sensor.

Definition at line 294 of file proto_constants.h.

RESULT_LIMITATION_BY_SAAC

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_SAAC = 0xEA

staticconstexpr

Parameter limited by a standalone automatic controller.

Definition at line 299 of file proto_constants.h.

RESULT_LIMITATION_BY_SCD

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_SCD = 0xE5

staticconstexpr

Parameter limited by a security actuator.

Definition at line 296 of file proto_constants.h.

RESULT_LIMITATION_BY_TIMER

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_TIMER = 0xE4

staticconstexpr

Parameter limited by a timer.

Definition at line 295 of file proto_constants.h.

RESULT_LIMITATION_BY_UNKNOWN_DEVICE

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_UNKNOWN_DEVICE = 0xE7

staticconstexpr

Parameter limited by an unknown device.

Definition at line 298 of file proto_constants.h.

RESULT_LIMITATION_BY_UPS

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_UPS = 0xE6

staticconstexpr

Parameter limited by a power supply.

Definition at line 297 of file proto_constants.h.

RESULT_LIMITATION_BY_USER

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_USER = 0xE2

staticconstexpr

Parameter limited by a remote control.

Definition at line 293 of file proto_constants.h.

RESULT_LIMITATION_BY_WIND

uint8_t esphome::home_io_control::RESULT_LIMITATION_BY_WIND = 0xEB

staticconstexpr

Parameter limited by a wind sensor.

Definition at line 300 of file proto_constants.h.

RESULT_LIMITS_NOT_SET

uint8_t esphome::home_io_control::RESULT_LIMITS_NOT_SET = 0x22

staticconstexpr

Device limits are not set.

Definition at line 280 of file proto_constants.h.

RESULT_LOCK_POSITION_OPEN

uint8_t esphome::home_io_control::RESULT_LOCK_POSITION_OPEN = 0x0D

staticconstexpr

Lock command failed because the door is open.

Definition at line 260 of file proto_constants.h.

RESULT_MANUALLY_OPERATED

uint8_t esphome::home_io_control::RESULT_MANUALLY_OPERATED = 0x03

staticconstexpr

Manually operated by a user.

Definition at line 250 of file proto_constants.h.

RESULT_MODE_NOT_IMPLEMENTED

uint8_t esphome::home_io_control::RESULT_MODE_NOT_IMPLEMENTED = 0x14

staticconstexpr

Mode is not supported by the node.

Definition at line 267 of file proto_constants.h.

RESULT_MOTION_TIME_TOO_LONG

uint8_t esphome::home_io_control::RESULT_MOTION_TIME_TOO_LONG = 0x0E

staticconstexpr

Target was not reached in time.

Definition at line 261 of file proto_constants.h.

RESULT_NO_CONTACT

uint8_t esphome::home_io_control::RESULT_NO_CONTACT = 0x02

staticconstexpr

No communication to node.

Definition at line 249 of file proto_constants.h.

RESULT_NO_EXECUTION

uint8_t esphome::home_io_control::RESULT_NO_EXECUTION = 0x09

staticconstexpr

Node did not move.

Definition at line 256 of file proto_constants.h.

RESULT_NODE_LOCKED

uint8_t esphome::home_io_control::RESULT_NODE_LOCKED = 0x20

staticconstexpr

Node is locked.

Definition at line 278 of file proto_constants.h.

RESULT_NODE_WAITING_FOR_POWER

uint8_t esphome::home_io_control::RESULT_NODE_WAITING_FOR_POWER = 0x1E

staticconstexpr

Node is waiting for power.

Definition at line 277 of file proto_constants.h.

RESULT_OUT_OF_RANGE

uint8_t esphome::home_io_control::RESULT_OUT_OF_RANGE = 0x24

staticconstexpr

Requested value is out of range.

Definition at line 282 of file proto_constants.h.

RESULT_PARAMETER_LIMITED

uint8_t esphome::home_io_control::RESULT_PARAMETER_LIMITED = 0xE0

staticconstexpr

Parameter limited by an unknown device.

Definition at line 291 of file proto_constants.h.

RESULT_POWER_CONSUMPTION_TOO_HIGH

uint8_t esphome::home_io_control::RESULT_POWER_CONSUMPTION_TOO_HIGH = 0x0B

staticconstexpr

Node power consumption is too high.

Definition at line 258 of file proto_constants.h.

RESULT_POWER_CONSUMPTION_TOO_LOW

uint8_t esphome::home_io_control::RESULT_POWER_CONSUMPTION_TOO_LOW = 0x0C

staticconstexpr

Node power consumption is too low.

Definition at line 259 of file proto_constants.h.

RESULT_PRIORITY_LEVEL_LOCKED

uint8_t esphome::home_io_control::RESULT_PRIORITY_LEVEL_LOCKED = 0x06

staticconstexpr

Node is locked on this priority level.

Definition at line 253 of file proto_constants.h.

RESULT_PRIORITY_LOCKED_NON_EXEC

uint8_t esphome::home_io_control::RESULT_PRIORITY_LOCKED_NON_EXEC

staticconstexpr

Initial value:

                                                     =
0x38

Priority locked, command not executed (ACEI priority too low).

Definition at line 283 of file proto_constants.h.

RESULT_PRODUCT_NOT_OPERATIONAL

uint8_t esphome::home_io_control::RESULT_PRODUCT_NOT_OPERATIONAL = 0x10

staticconstexpr

Node is not currently operational.

Definition at line 263 of file proto_constants.h.

RESULT_REACHED_WRONG_POSITION

uint8_t esphome::home_io_control::RESULT_REACHED_WRONG_POSITION = 0x07

staticconstexpr

Node stopped in another position than expected.

Definition at line 254 of file proto_constants.h.

RESULT_TARGET_MODIFIED

uint8_t esphome::home_io_control::RESULT_TARGET_MODIFIED = 0x13

staticconstexpr

Node modified the requested target value.

Definition at line 266 of file proto_constants.h.

RESULT_TARGET_NOT_REACHABLE

uint8_t esphome::home_io_control::RESULT_TARGET_NOT_REACHABLE = 0x1B

staticconstexpr

Requested target not reachable.

Definition at line 274 of file proto_constants.h.

RESULT_THERMAL_PROTECTION

uint8_t esphome::home_io_control::RESULT_THERMAL_PROTECTION = 0x0F

staticconstexpr

Node entered thermal protection mode.

Definition at line 262 of file proto_constants.h.

RESULT_UNKNOWN_STATUS_REPLY

uint8_t esphome::home_io_control::RESULT_UNKNOWN_STATUS_REPLY = 0x00

staticconstexpr

Device returned an unknown status reply.

Definition at line 247 of file proto_constants.h.

RESULT_USER_ACTION

uint8_t esphome::home_io_control::RESULT_USER_ACTION = 0x16

staticconstexpr

User action overrode the command.

Definition at line 269 of file proto_constants.h.

RESULT_WRONG_LOAD_CONNECTED

uint8_t esphome::home_io_control::RESULT_WRONG_LOAD_CONNECTED = 0x19

staticconstexpr

Wrong load connected to node.

Definition at line 272 of file proto_constants.h.

RESULT_WRONG_POSITION

uint8_t esphome::home_io_control::RESULT_WRONG_POSITION = 0x21

staticconstexpr

Node reports wrong position.

Definition at line 279 of file proto_constants.h.

RESULT_WRONG_SYSTEMKEY

uint8_t esphome::home_io_control::RESULT_WRONG_SYSTEMKEY = 0x05

staticconstexpr

Node contains the wrong system key.

Definition at line 252 of file proto_constants.h.

RSSI_EMA_SCALE

int16_t esphome::home_io_control::RSSI_EMA_SCALE = 8

staticconstexpr

EMA weight denominator and fixed-point scale for IoDevice::rssi_ema_scaled.

One constant serves both roles by construction: the update S += x − round(S/N) blends each new sample x in at weight 1/N while keeping S = N × EMA.

Definition at line 266 of file proto_device_model.h.

RSSI_UNKNOWN_DBM

int16_t esphome::home_io_control::RSSI_UNKNOWN_DBM = INT16_MIN

staticconstexpr

Sentinel value meaning "no RSSI sample recorded yet" for last_rssi_dbm/rssi_ema_scaled.

A real RSSI reading from these radios is always well above INT16_MIN — and so is any real rssi_ema_scaled fixed-point value.

Definition at line 261 of file proto_device_model.h.

RX_HOP_HOLDOFF_US

uint32_t esphome::home_io_control::RX_HOP_HOLDOFF_US = 12000

inlineconstexpr

Longest a frame arriving on the current channel may hold off an idle-path channel hop, in microseconds.

Sized to outlast the slowest thing a hop could destroy. On the software-PHY chips that is the fixed-length RX_DONE, which lands 48 raw bytes = 10.0 ms after the sync word (SOFT_PHY_RX_PROBE_PACKET_LEN at 38400 bps; a static_assert in radio_soft_phy_driver_base.h ties this constant to that arithmetic, since neither header can see the other's constants). On the SX1276 it is the frame's own air time, at most ~9.4 ms for the longest possible frame. 12 ms covers both with margin for poll granularity.

It is a bound, not a target: every mechanism that sets the holdoff is expected to clear it early, and the bound exists only so that a sync detection with no frame behind it — noise, a truncated burst, a peer that gave up — cannot wedge channel hopping permanently.

Definition at line 38 of file radio_interface.h.

SCHEDULED_POLL_MAX_TRIES

uint8_t esphome::home_io_control::SCHEDULED_POLL_MAX_TRIES = 1

staticconstexpr

Exchange tries for a status poll the scheduler owns — every status poll issued while StatusPollPolicy is tracking the device, which today is every status poll this component can produce (there is no user-facing "refresh status" button or action; if one is ever added, it must not take this branch).

Such a poll's failure is re-armed by the backoff ladder (STATUS_RETRY_AFTER_FAIL_MS and its successors), so the ladder is its retry mechanism; stacking EXCHANGE_RETRY_COUNT blocking in-exchange tries on top of it buys no freshness and costs ~1.6 s of blocked loop() while a device is unresponsive (e.g. an actuator mid-manoeuvre) — the settle poll fires seconds after a command, squarely inside the manoeuvre, so keeping it a single try is what lets a STOP a user presses mid-move dispatch promptly. A poll with no ladder behind it keeps the full EXCHANGE_RETRY_COUNT. See SCHEDULED_POLL_RETRY_GRACE_FIRST_FAILURE below for the one place this trade-off is deliberately bought back.

Definition at line 127 of file proto_timing.h.

SCHEDULED_POLL_RETRY_GRACE_FIRST_FAILURE

uint8_t esphome::home_io_control::SCHEDULED_POLL_RETRY_GRACE_FIRST_FAILURE = 1

staticconstexpr

Ladder positions at which a scheduler-owned status poll gets the full EXCHANGE_RETRY_COUNT back.

The single try above is right at both ends of the backoff ladder and wrong in the middle. At the first slot after a command the device is still executing the manoeuvre: its silence is expected, retries cannot change that, and blocking loop() for the full retry product would delay a STOP the user presses mid-move. Once a device has missed several slots in a row it is unreachable rather than merely asleep, and retries are just as pointless. In between sits the slot where the manoeuvre has just ended and the device is awake again but duty-cycled — one 400 ms listen samples its receive window once; EXCHANGE_RETRY_COUNT tries sample it three times, ~870 ms apart, and a success there also clears the failure streak and ends the backoff.

Counted in consecutive silent failures already recorded when the poll is dispatched, so 0 is the post-command settle poll and 1..3 are the ~5 s / ~15 s / ~30 s ladder slots after it — roughly t+8 s to t+53 s, spanning every cover travel time this project has measured. An auth-shaped streak is excluded entirely: a device that answers with a 0x3C challenge is awake, so extra tries buy no wake-up, and an auth try is the most expensive shape the engine runs.

Definition at line 145 of file proto_timing.h.

SCHEDULED_POLL_RETRY_GRACE_LAST_FAILURE

uint8_t esphome::home_io_control::SCHEDULED_POLL_RETRY_GRACE_LAST_FAILURE = 3

staticconstexpr

Definition at line 146 of file proto_timing.h.

SELECT_PARAMS

TuningSelectParam esphome::home_io_control::SELECT_PARAMS[]

staticconstexpr

Definition at line 86 of file tuning_registry.cpp.

SHORT_PREAMBLE

uint16_t esphome::home_io_control::SHORT_PREAMBLE = 8

staticconstexpr

8 bytes for response/continuation frames

Definition at line 33 of file proto_timing.h.

SOFT_PHY_ALL_IRQ_BITS

uint32_t esphome::home_io_control::SOFT_PHY_ALL_IRQ_BITS = 0xFFFFFFFF

staticconstexpr

Sentinel meaning "every IRQ bit counts as activity" — the default for SoftPhyDriverBase::activity_irq_mask.

Neither concrete driver uses it any more: both SX1262 and LR1121 unmask PreambleDetected at the hardware level and override this to exclude it (see SX1262_IRQ_ACTIVITY_MASK / LR1121_IRQ_ACTIVITY_MASK). Kept as the base-class default for a hypothetical future driver that never unmasks PreambleDetected in the first place, where "any bit" is genuinely safe again.

Definition at line 47 of file radio_soft_phy_driver_base.h.

SOFT_PHY_EARLY_HEADER_RAW_BYTES

uint8_t esphome::home_io_control::SOFT_PHY_EARLY_HEADER_RAW_BYTES = 3

staticconstexpr

Raw bytes read in the first stage of a length-driven receive — enough to hold CTRL0's UART cell (10 bits) at any of the probe's bit alignments (up to 9 bits of slack).

Definition at line 51 of file radio_soft_phy_driver_base.h.

SOFT_PHY_EARLY_MIN_WINDOW_MS

uint32_t esphome::home_io_control::SOFT_PHY_EARLY_MIN_WINDOW_MS = 12

staticconstexpr

Smallest receive window a length-driven receive will be attempted in, in milliseconds.

The longest possible frame (FRAME_MAX_SIZE + CRC, UART-packed) occupies ~9.4 ms of air time, so a caller with less than this left cannot finish one either way. Declining up front keeps the early path from spending a short window's whole budget on a receive it cannot complete.

Definition at line 68 of file radio_soft_phy_driver_base.h.

SOFT_PHY_EARLY_POLL_US

uint32_t esphome::home_io_control::SOFT_PHY_EARLY_POLL_US = 100

staticconstexpr

Poll interval while waiting out a frame's remaining air time, in microseconds.

Definition at line 61 of file radio_soft_phy_driver_base.h.

SOFT_PHY_EARLY_READ_MARGIN_BYTES

uint8_t esphome::home_io_control::SOFT_PHY_EARLY_READ_MARGIN_BYTES = 2

staticconstexpr

Air-time margin added before every mid-reception buffer read, in raw bytes.

Covers the lag between a byte finishing on air and the chip having it in its data buffer, plus the granularity of the polled sync-word observation. Two byte-times is generous at this line rate and still leaves a length-driven receive far ahead of the fixed-length RX_DONE.

Definition at line 58 of file radio_soft_phy_driver_base.h.

SOFT_PHY_IDLE_RX_COMPLETION_BUDGET_MS

uint32_t esphome::home_io_control::SOFT_PHY_IDLE_RX_COMPLETION_BUDGET_MS = 20

staticconstexpr

Blocking budget SoftPhyDriverBase::check_for_packet gives a length-driven receive, in milliseconds — the timeout_ms passed to try_early_completion_() from the non-blocking idle-loop RX path (issue #81).

The real bound on how long that call can block is the frame's own air time (~9.4 ms worst case, see SOFT_PHY_EARLY_MIN_WINDOW_MS), not this number; this value only has to be large enough not to cut a genuine frame short. It is not itself a tight bound on loop() latency — the actual air time is what stays well inside a loop() tick (~16-30 ms) — and either way it is dwarfed by the 1-3 s a blocking exchange already costs loop().

Definition at line 78 of file radio_soft_phy_driver_base.h.

SOFT_PHY_LINE_RATE_BPS

uint32_t esphome::home_io_control::SOFT_PHY_LINE_RATE_BPS = 38400

staticconstexpr

Protocol line rate. The same 38400 bps every driver programs into its own bitrate register.

Definition at line 85 of file radio_soft_phy_driver_base.h.

SOFT_PHY_RX_PROBE_PACKET_LEN

uint8_t esphome::home_io_control::SOFT_PHY_RX_PROBE_PACKET_LEN = 48

staticconstexpr

Fixed raw-RX probe length: chosen from captures of 23-25 byte protocol frames after UART packing and CRC appending — the longest frame (25 bytes + 2 CRC) UART-packs to 34 raw bytes, so 48 bytes preserves complete traffic (with margin for leading noise before the frame start) without relying on either chip's variable-length engine.

This is a protocol-frame-size property, not a chip quirk, so both drivers share one value — used here for the raw-probe threshold in SoftPhyDriverBase::read_rx_packet and by each driver's own set_rx_packet_params() for the configured RX payload length.

Definition at line 39 of file radio_soft_phy_driver_base.h.

SOFT_PHY_US_PER_SECOND

uint32_t esphome::home_io_control::SOFT_PHY_US_PER_SECOND = 1000000

staticconstexpr

Microseconds in a second, for the air-time arithmetic below.

Definition at line 87 of file radio_soft_phy_driver_base.h.

STATUS_AUTH_RETRY_AFTER_FAIL_MAX_MS

uint32_t esphome::home_io_control::STATUS_AUTH_RETRY_AFTER_FAIL_MAX_MS = 300000

staticconstexpr

Steady-state after repeated auth failures.

Definition at line 33 of file status_poll_policy.h.

STATUS_AUTH_RETRY_AFTER_FAIL_MS

uint32_t esphome::home_io_control::STATUS_AUTH_RETRY_AFTER_FAIL_MS = 30000

staticconstexpr

First retry after a challenge-seen failure.

Definition at line 31 of file status_poll_policy.h.

STATUS_AUTH_RETRY_AFTER_FAIL_STEP2_MS

uint32_t esphome::home_io_control::STATUS_AUTH_RETRY_AFTER_FAIL_STEP2_MS = 120000

staticconstexpr

Second retry.

Definition at line 32 of file status_poll_policy.h.

STATUS_EXPECTED

uint8_t esphome::home_io_control::STATUS_EXPECTED = 0x80

staticconstexpr

Byte 1 bit 7: device will send auto status update.

Definition at line 363 of file proto_constants.h.

STATUS_POS_MAX

uint16_t esphome::home_io_control::STATUS_POS_MAX = 0xC800

staticconstexpr

In status responses, position is encoded as a 16-bit value where 0x0000 = fully open (0%) and 0xC800 = fully closed (100%).

Definition at line 236 of file proto_device_model.h.

STATUS_POS_TOLERANCE_RAW

uint16_t esphome::home_io_control::STATUS_POS_TOLERANCE_RAW = 100

staticconstexpr

Target-reached tolerance expressed in raw IO-homecontrol position units.

100 raw units out of 51200 full-scale is about 0.195%, so this only absorbs tiny target/current mismatches from device rounding or early stopped flags.

Definition at line 240 of file proto_device_model.h.

STATUS_RETRY_AFTER_FAIL_MAX_MS

uint32_t esphome::home_io_control::STATUS_RETRY_AFTER_FAIL_MAX_MS

staticconstexpr

Initial value:

                                                     =
300000

Steady-state backoff after many silent failures.

Definition at line 25 of file status_poll_policy.h.

STATUS_RETRY_AFTER_FAIL_MS

uint32_t esphome::home_io_control::STATUS_RETRY_AFTER_FAIL_MS = 5000

staticconstexpr

First retry after a silent failure.

Definition at line 21 of file status_poll_policy.h.

STATUS_RETRY_AFTER_FAIL_STEP2_MS

uint32_t esphome::home_io_control::STATUS_RETRY_AFTER_FAIL_STEP2_MS = 15000

staticconstexpr

Second retry after a silent failure.

Definition at line 22 of file status_poll_policy.h.

STATUS_RETRY_AFTER_FAIL_STEP3_MS

uint32_t esphome::home_io_control::STATUS_RETRY_AFTER_FAIL_STEP3_MS = 30000

staticconstexpr

Third retry after a silent failure.

Definition at line 23 of file status_poll_policy.h.

STATUS_RETRY_AFTER_FAIL_STEP4_MS

uint32_t esphome::home_io_control::STATUS_RETRY_AFTER_FAIL_STEP4_MS = 60000

staticconstexpr

Fourth retry after a silent failure.

Definition at line 24 of file status_poll_policy.h.

STATUS_STOPPED

uint8_t esphome::home_io_control::STATUS_STOPPED = 0x01

staticconstexpr

Status byte flags in CMD_PRIVATE_RESP and CMD_STATUS_UPDATE.

Byte 0 bit 0: device is not moving

Definition at line 362 of file proto_constants.h.

STATUS_TILT_SELECTOR

uint8_t esphome::home_io_control::STATUS_TILT_SELECTOR = 0x20

staticconstexpr

Extended status payload marker for tilt-capable devices.

Definition at line 364 of file proto_constants.h.

STOP_SETTLE_POLL_CAP_MS

uint32_t esphome::home_io_control::STOP_SETTLE_POLL_CAP_MS = 1000

staticconstexpr

Upper bound on the settle-poll delay after a STOP command.

STOP should confirm the resting position quickly, so it always settles faster than a normal move, regardless of the configured interval or device hint.

Definition at line 62 of file status_poll_policy.h.

SX1262_BUSY_TIMEOUT_MS

uint32_t esphome::home_io_control::SX1262_BUSY_TIMEOUT_MS = 10

staticconstexpr

How long SoftPhyDriverBase::wait_busy_() waits for BUSY to drop before declaring the chip failed.

Short: this chip's RC-oscillator-clocked commands settle quickly, unlike LR1121's post-reset boot ROM (see LR1121_BUSY_TIMEOUT_MS in radio_lr1121.h).

Definition at line 107 of file radio_sx1262.h.

SX1262_CALIBRATE

uint8_t esphome::home_io_control::SX1262_CALIBRATE = 0x89

staticconstexpr

Definition at line 48 of file radio_sx1262.h.

SX1262_CALIBRATE_IMAGE

uint8_t esphome::home_io_control::SX1262_CALIBRATE_IMAGE = 0x98

staticconstexpr

Definition at line 49 of file radio_sx1262.h.

SX1262_CLEAR_DEVICE_ERRORS

uint8_t esphome::home_io_control::SX1262_CLEAR_DEVICE_ERRORS = 0x07

staticconstexpr

Definition at line 39 of file radio_sx1262.h.

SX1262_CLEAR_IRQ_STATUS

uint8_t esphome::home_io_control::SX1262_CLEAR_IRQ_STATUS = 0x02

staticconstexpr

Definition at line 38 of file radio_sx1262.h.

SX1262_DISCOVERY_HOP_SLICE_MS

uint16_t esphome::home_io_control::SX1262_DISCOVERY_HOP_SLICE_MS = 7

staticconstexpr

Per-channel dwell while SX1262 pairing discovery hops across channels.

SX1262 frequency changes require a standby→SetRfFrequency→RX cycle, unlike the SX1276's FastHop, but that changes only how much a single retune costs, not how long the radio should then sit still: a short dwell fits more retunes into the listen window than a long one, so the receiver is more often already parked on the right channel by the time a reply starts. The preamble/sync linger guard (ListenSpec::linger_on_preamble) is what makes a dwell this short safe — it keeps a caught reply from being cut off mid-reception by extending the dwell instead of hopping away. A dwell in the low single-digit milliseconds performs best; shorter than that, coverage degrades gradually and only truly collapses at 0, where wait_for_packet(..., 0) returns before any guard can observe activity at all. 7 is the best-performing value found in that range.

Definition at line 139 of file tuning_config.h.

SX1262_FALLBACK_STDBY_XOSC

uint8_t esphome::home_io_control::SX1262_FALLBACK_STDBY_XOSC = 0x30

staticconstexpr

Definition at line 102 of file radio_sx1262.h.

SX1262_GET_DEVICE_ERRORS

uint8_t esphome::home_io_control::SX1262_GET_DEVICE_ERRORS = 0x17

staticconstexpr

Definition at line 37 of file radio_sx1262.h.

SX1262_GET_IRQ_STATUS

uint8_t esphome::home_io_control::SX1262_GET_IRQ_STATUS = 0x12

staticconstexpr

Definition at line 35 of file radio_sx1262.h.

SX1262_GET_PACKET_STATUS

uint8_t esphome::home_io_control::SX1262_GET_PACKET_STATUS = 0x14

staticconstexpr

Definition at line 36 of file radio_sx1262.h.

SX1262_GET_RSSI_INST

uint8_t esphome::home_io_control::SX1262_GET_RSSI_INST = 0x15

staticconstexpr

Definition at line 51 of file radio_sx1262.h.

SX1262_GET_RX_BUFFER_STATUS

uint8_t esphome::home_io_control::SX1262_GET_RX_BUFFER_STATUS = 0x13

staticconstexpr

Definition at line 50 of file radio_sx1262.h.

SX1262_GET_STATUS

uint8_t esphome::home_io_control::SX1262_GET_STATUS = 0xC0

staticconstexpr

Definition at line 53 of file radio_sx1262.h.

SX1262_GFSK_CRC_OFF

uint8_t esphome::home_io_control::SX1262_GFSK_CRC_OFF = 0x01

staticconstexpr

Definition at line 101 of file radio_sx1262.h.

SX1262_GFSK_PACKET_TYPE_KNOWN_LENGTH

uint8_t esphome::home_io_control::SX1262_GFSK_PACKET_TYPE_KNOWN_LENGTH = 0x00

staticconstexpr

Definition at line 100 of file radio_sx1262.h.

SX1262_IRQ_ACTIVITY_MASK

uint16_t esphome::home_io_control::SX1262_IRQ_ACTIVITY_MASK

staticconstexpr

Initial value:

                                               =
SX1262_IRQ_TX_DONE | SX1262_IRQ_RX_DONE | SX1262_IRQ_SYNC_WORD_VALID | SX1262_IRQ_CRC_ERR

IRQ bits that represent a terminal radio event — a frame finished decoding, an outbound frame completed, or the chip reported a bad CRC.

Deliberately excludes PREAMBLE_DETECTED even though configure_radio_() now includes it in irqMask: a preamble alone means a frame may still be arriving, so SoftPhyDriverBase's poll_until_activity_()/check_for_packet() (gated by RadioSX1262::activity_irq_mask) must not treat it as terminal — doing so would tear down RX mid-reception. Same trap, same fix shape as LR1121_IRQ_ACTIVITY_MASK.

Definition at line 75 of file radio_sx1262.h.

SX1262_IRQ_CRC_ERR

uint16_t esphome::home_io_control::SX1262_IRQ_CRC_ERR = 0x0040

staticconstexpr

Definition at line 67 of file radio_sx1262.h.

SX1262_IRQ_PREAMBLE_DETECTED

uint16_t esphome::home_io_control::SX1262_IRQ_PREAMBLE_DETECTED = 0x0004

staticconstexpr

Definition at line 65 of file radio_sx1262.h.

SX1262_IRQ_RX_DONE

uint16_t esphome::home_io_control::SX1262_IRQ_RX_DONE = 0x0002

staticconstexpr

Definition at line 64 of file radio_sx1262.h.

SX1262_IRQ_SYNC_WORD_VALID

uint16_t esphome::home_io_control::SX1262_IRQ_SYNC_WORD_VALID = 0x0008

staticconstexpr

Definition at line 66 of file radio_sx1262.h.

SX1262_IRQ_TX_DONE

uint16_t esphome::home_io_control::SX1262_IRQ_TX_DONE = 0x0001

staticconstexpr

Definition at line 63 of file radio_sx1262.h.

SX1262_POST_TX_SETTLE_US

uint16_t esphome::home_io_control::SX1262_POST_TX_SETTLE_US = 500

staticconstexpr

SX1262-specific post-TX settling delay before re-entering RX.

The SX1262 GFSK demodulator needs time to stabilize after TX before it can reliably receive the next frame. A 500 µs delay was validated as the minimum that prevents challenge-byte corruption during pairing and tight-turnaround authenticated exchanges.

Definition at line 112 of file tuning_config.h.

SX1262_READ_BUFFER

uint8_t esphome::home_io_control::SX1262_READ_BUFFER = 0x1E

staticconstexpr

Definition at line 33 of file radio_sx1262.h.

SX1262_READ_REGISTER

uint8_t esphome::home_io_control::SX1262_READ_REGISTER = 0x1D

staticconstexpr

Definition at line 57 of file radio_sx1262.h.

SX1262_REG_RX_GAIN

uint16_t esphome::home_io_control::SX1262_REG_RX_GAIN = 0x08AC

staticconstexpr

Definition at line 79 of file radio_sx1262.h.

SX1262_REG_SYNC_WORD

uint16_t esphome::home_io_control::SX1262_REG_SYNC_WORD = 0x06C0

staticconstexpr

Definition at line 78 of file radio_sx1262.h.

SX1262_REG_TX_CLAMP_CONFIG

uint16_t esphome::home_io_control::SX1262_REG_TX_CLAMP_CONFIG = 0x08D8

staticconstexpr

Definition at line 80 of file radio_sx1262.h.

SX1262_REG_TX_MODULATION

uint16_t esphome::home_io_control::SX1262_REG_TX_MODULATION = 0x0889

staticconstexpr

TX modulation-quality erratum register (SX1262 datasheet §15.1, "Modulation Quality with 500 kHz LoRa Bandwidth" — the title names LoRa, but the workaround table covers every modulation).

Bit 2 must be cleared only for LoRa at BW 500 kHz and set to 1 for everything else, explicitly including any (G)FSK configuration — which is all this driver ever uses. Semtech's own driver and RadioLib apply it as TxModulation / fixModulationQuality(). Leaving it at its reset value degrades transmitted modulation quality, which on this protocol shows up as a peer that intermittently fails to decode an otherwise strong frame. Counterpart to the already-applied TxClamp erratum (SX1262_REG_TX_CLAMP_CONFIG).

Definition at line 90 of file radio_sx1262.h.

SX1262_RESPONSE_PREAMBLE

uint16_t esphome::home_io_control::SX1262_RESPONSE_PREAMBLE = 8

staticconstexpr

SX1262-specific preamble for response/continuation frames within an exchange.

Applies to any tight-turnaround frame sent immediately after receiving from the device — 0x3D challenge responses, 0x32 key transfers after receiving 0x3C, and any future protocol frame in that position — giving the peer's receiver time to lock back on after the SX1262's own TX→RX turnaround.

8 bytes was validated on real hardware (Heltec V3.2 ↔ Device actuator) as the minimum that gives reliable lock-on without perturbing exchange timing; it matches the protocol's own nominal SHORT_PREAMBLE floor.

This constant is byte-denominated, like every other preamble value in this codebase (LONG_PREAMBLE, SHORT_PREAMBLE) — RadioSX1262::set_packet_params_() is the one place that converts to the chip's bit-denominated SetPacketParams field, right before the value leaves for the wire.

Definition at line 104 of file tuning_config.h.

SX1262_RX_BUFFER_BASE

uint8_t esphome::home_io_control::SX1262_RX_BUFFER_BASE = 0x80

staticconstexpr

Definition at line 98 of file radio_sx1262.h.

SX1262_SET_BUFFER_BASE_ADDRESS

uint8_t esphome::home_io_control::SX1262_SET_BUFFER_BASE_ADDRESS = 0x8F

staticconstexpr

Definition at line 43 of file radio_sx1262.h.

SX1262_SET_DIO2_AS_RF_SWITCH_CTRL

uint8_t esphome::home_io_control::SX1262_SET_DIO2_AS_RF_SWITCH_CTRL = 0x9D

staticconstexpr

Definition at line 46 of file radio_sx1262.h.

SX1262_SET_DIO3_AS_TCXO_CTRL

uint8_t esphome::home_io_control::SX1262_SET_DIO3_AS_TCXO_CTRL = 0x97

staticconstexpr

Definition at line 47 of file radio_sx1262.h.

SX1262_SET_DIO_IRQ_PARAMS

uint8_t esphome::home_io_control::SX1262_SET_DIO_IRQ_PARAMS = 0x08

staticconstexpr

Definition at line 34 of file radio_sx1262.h.

SX1262_SET_MODULATION_PARAMS

uint8_t esphome::home_io_control::SX1262_SET_MODULATION_PARAMS = 0x8B

staticconstexpr

Definition at line 41 of file radio_sx1262.h.

SX1262_SET_PA_CONFIG

uint8_t esphome::home_io_control::SX1262_SET_PA_CONFIG = 0x95

staticconstexpr

Definition at line 44 of file radio_sx1262.h.

SX1262_SET_PACKET_PARAMS

uint8_t esphome::home_io_control::SX1262_SET_PACKET_PARAMS = 0x8C

staticconstexpr

Definition at line 42 of file radio_sx1262.h.

SX1262_SET_PACKET_TYPE

uint8_t esphome::home_io_control::SX1262_SET_PACKET_TYPE = 0x8A

staticconstexpr

Definition at line 40 of file radio_sx1262.h.

SX1262_SET_REGULATOR_MODE

uint8_t esphome::home_io_control::SX1262_SET_REGULATOR_MODE = 0x96

staticconstexpr

Definition at line 52 of file radio_sx1262.h.

SX1262_SET_RF_FREQUENCY

uint8_t esphome::home_io_control::SX1262_SET_RF_FREQUENCY = 0x86

staticconstexpr

Definition at line 30 of file radio_sx1262.h.

SX1262_SET_RX

uint8_t esphome::home_io_control::SX1262_SET_RX = 0x82

staticconstexpr

Definition at line 28 of file radio_sx1262.h.

SX1262_SET_RX_TX_FALLBACK_MODE

uint8_t esphome::home_io_control::SX1262_SET_RX_TX_FALLBACK_MODE = 0x93

staticconstexpr

Definition at line 31 of file radio_sx1262.h.

SX1262_SET_STANDBY

uint8_t esphome::home_io_control::SX1262_SET_STANDBY = 0x80

staticconstexpr

Definition at line 27 of file radio_sx1262.h.

SX1262_SET_TX

uint8_t esphome::home_io_control::SX1262_SET_TX = 0x83

staticconstexpr

Definition at line 29 of file radio_sx1262.h.

SX1262_SET_TX_PARAMS

uint8_t esphome::home_io_control::SX1262_SET_TX_PARAMS = 0x8E

staticconstexpr

Definition at line 45 of file radio_sx1262.h.

SX1262_SYNC_WORD_PARAM_24_BITS

const uint8_t esphome::home_io_control::SX1262_SYNC_WORD_PARAM_24_BITS = 0x18

static

Definition at line 29 of file radio_sx1262.cpp.

SX1262_TX_BUFFER_BASE

uint8_t esphome::home_io_control::SX1262_TX_BUFFER_BASE = 0x00

staticconstexpr

Data-buffer split programmed by configure_buffer_base(): TX packets build from 0x00, RX packets land at 0x80.

The RX base doubles as the read offset for a length-driven receive — a single in-flight packet always starts exactly there.

Definition at line 97 of file radio_sx1262.h.

SX1262_TX_MODULATION_GFSK_BIT

uint8_t esphome::home_io_control::SX1262_TX_MODULATION_GFSK_BIT = 0x04

staticconstexpr

Bit 2 of SX1262_REG_TX_MODULATION — the (G)FSK-correct value is 1.

Definition at line 92 of file radio_sx1262.h.

SX1262_WRITE_BUFFER

uint8_t esphome::home_io_control::SX1262_WRITE_BUFFER = 0x0E

staticconstexpr

Definition at line 32 of file radio_sx1262.h.

SX1262_WRITE_REGISTER

uint8_t esphome::home_io_control::SX1262_WRITE_REGISTER = 0x0D

staticconstexpr

Definition at line 56 of file radio_sx1262.h.

SX1276_DISCOVERY_HOP_SLICE_MS

uint16_t esphome::home_io_control::SX1276_DISCOVERY_HOP_SLICE_MS = 5

staticconstexpr

Per-channel dwell while SX1276 pairing discovery hops across channels.

The SX1276 supports FastHop (no standby transition), so a short slice keeps discovery sweeping all three channels quickly.

Definition at line 125 of file tuning_config.h.

SX1276_RESPONSE_PREAMBLE

uint16_t esphome::home_io_control::SX1276_RESPONSE_PREAMBLE = 12

staticconstexpr

SX1276 preamble for response/continuation frames within an exchange.

Defaults to 12 bytes — longer than the protocol's 8-byte SHORT_PREAMBLE. On real hardware the extra length improves the peer device's lock-on without measurably affecting exchange timing. Runtime-tunable down to SHORT_PREAMBLE or up for a marginal-range install.

Definition at line 119 of file tuning_config.h.

TAG [1/12]

const char* esphome::home_io_control::TAG = "home_io_control"

staticconstexpr

Definition at line 15 of file device_registry.cpp.

TAG [2/12]

const char* const esphome::home_io_control::TAG = "home_io_control.exchange"

static

Definition at line 27 of file exchange_engine.cpp.

TAG [3/12]

const char* const esphome::home_io_control::TAG = detail::TAG

static

Definition at line 37 of file hub_core.cpp.

TAG [4/12]

const char* const esphome::home_io_control::TAG = "home_io_control.climate"

static

Definition at line 15 of file platform_climate.cpp.

TAG [5/12]

const char* const esphome::home_io_control::TAG = "home_io_control.cover"

static

Definition at line 12 of file platform_cover.cpp.

TAG [6/12]

const char* const esphome::home_io_control::TAG = "home_io_control.light"

static

Definition at line 12 of file platform_light.cpp.

TAG [7/12]

const char* const esphome::home_io_control::TAG = "home_io_control.lock"

static

Definition at line 13 of file platform_lock.cpp.

TAG [8/12]

const char* const esphome::home_io_control::TAG = "home_io_control.switch"

static

Definition at line 12 of file platform_switch.cpp.

TAG [9/12]

const char* const esphome::home_io_control::TAG = "home_io_control.lr1121"

static

Definition at line 27 of file radio_lr1121.cpp.

TAG [10/12]

const char* const esphome::home_io_control::TAG = "home_io_control.soft_phy"

static

Definition at line 23 of file radio_soft_phy_driver_base.cpp.

TAG [11/12]

const char* const esphome::home_io_control::TAG = "home_io_control.sx1262"

static

Definition at line 28 of file radio_sx1262.cpp.

TAG [12/12]

const char* const esphome::home_io_control::TAG = "home_io_control.sx1276"

static

Definition at line 20 of file radio_sx1276.cpp.

TAG_COMMAND_BUTTON

const char* const esphome::home_io_control::TAG_COMMAND_BUTTON = "home_io_control.cover_command_button"

static

Definition at line 15 of file platform_cover_controls.cpp.

TAG_SILENT

const char* const esphome::home_io_control::TAG_SILENT = "home_io_control.cover.silent"

static

Definition at line 16 of file platform_cover_controls.cpp.

TRANSFER_KEY

uint8_t esphome::home_io_control::TRANSFER_KEY[AES_KEY_SIZE]

staticconstexpr

Initial value:

= {0x34, 0xC3, 0x46, 0x6E, 0xD8, 0x8F, 0x4E, 0x8E,
                 0x16, 0xAA, 0x47, 0x39, 0x49, 0x88, 0x43, 0x73}

The transfer key is a hardcoded key used ONLY during pairing to obfuscate the system key during over-the-air transfer.

It is NOT the system key. This is the same across all IO-Homecontrol devices worldwide.

Definition at line 381 of file proto_constants.h.

UART_CELL_BITS

uint8_t esphome::home_io_control::UART_CELL_BITS = 10

staticconstexpr

Bits an on-air UART cell spends per protocol byte: start(1) + data(8) + stop(1).

Definition at line 50 of file radio_soft_phy.h.

UART_PROBE_MAX_BIT_OFFSET

const uint8_t esphome::home_io_control::UART_PROBE_MAX_BIT_OFFSET = 10

static

Maximum bit offset to search for valid UART decode start position.

The UART frame is 10 bits (start + 8 data). If the sync word is not aligned, we probe up to 10 bits offset to recover the correct framing.

Definition at line 23 of file radio_soft_phy.cpp.

UNKNOWN_POSITION

float esphome::home_io_control::UNKNOWN_POSITION = 212.0F

staticconstexpr

Sentinel value meaning "position is not known yet".

Matches POS_UNKNOWN (0xD4 = 212 decimal) for easy debugging.

Definition at line 255 of file proto_device_model.h.

VELUX_KLI_ENROLLMENT_CLASSES

std::array<DeviceType, 3> esphome::home_io_control::VELUX_KLI_ENROLLMENT_CLASSES

staticconstexpr

Initial value:

{DeviceType::ROLLER_SHUTTER, DeviceType::AWNING,
                                                                        DeviceType::DUAL_SHUTTER}

The three device classes a real VELUX KLI PROG gesture sweeps its 0x30 across — roller shutter, awning, dual shutter — and never any other (issue #74 capture, decoded with broadcast_target_type(); matches samr037/iohc-flipper's PAIR_DST_{WINDOW,SHUTTER,OTHER}).

Definition at line 102 of file oneway_controller.h.