proto_commands.h

Go to the documentation of this file.

#pragma once
 
/// @file proto_commands.h
/// @brief Command builders for the IO‑Homecontrol protocol.
/// @ingroup hioc_protocol
///
/// This module provides builder functions that populate IoFrame structures for
/// the various commands used in discovery, pairing, control, and status operations.
/// All builders follow the same pattern: fill an IoFrame with CTRL0/CTRL1 flags,
/// addresses, command ID, and optional payload.
///
/// Position encoding:
///   - IO protocol position values: 0 = fully open, 100 = fully closed, for a non-inverted
///     device — but this is per-device, not a universal wire constant: IoDevice::inverted
///     devices (e.g. horizontal awnings) have it backwards (0 = fully closed, 100 = fully
///     open). Never hardcode "0 = open" in caller code without checking inversion first.
///   - Use create_execute_position() for numeric positions (0–100).
///   - Use create_execute_command() for named commands: CoverCommand::STOP,
///     CoverCommand::FAVORITE, CoverCommand::VENT, CoverCommand::PEDESTRIAN, CoverCommand::PARTIAL.
///   - Use create_force_open() for CoverCommand::FORCE_OPEN — it takes the target "fully open"
///     position explicitly rather than assuming 0
///   - The Home Assistant layer maps HA's 1.0=open/0.0=closed to the IO scale via
///     ha_position = 1.0 - (io_position / 100.0), or the inverted form for IoDevice::inverted
///     devices; see platform_cover.h.
///
/// Low‑power flag and preamble handling:
///   - CTRL1_LOW_POWER is a per‑device property on the command path. Every device‑addressed
///     builder on that path takes an explicit `low_power` argument, set from the target's
///     YAML‑declared `low_power` class (default false: an always‑listening receiver).
///     Battery/solar devices that duty‑cycle their receiver get the flag; mains devices do not,
///     matching a reference hub's own traffic. The pairing and device‑role builders
///     (`create_key_init`, `create_key_transfer`, `create_set_config1`,
///     `create_status_update_resp`) keep a fixed value instead — see ADR 0029's out‑of‑scope note.
///     `create_discover_confirm()` is the one pairing builder that does NOT keep a fixed value: its
///     `low_power` follows the discovered device's own self-reported power-save class instead, the
///     same per-device-property treatment as every non-pairing builder above — every real hub in
///     this project's corpus mirrors that class exactly on its own 0x2C.
///   - The preamble follows the flag. For a start frame the exchange engine uses LONG_PREAMBLE
///     (1024 bytes) when CTRL1_LOW_POWER is set — the wake‑up burst for a sleeping receiver —
///     and the runtime‑tunable `normal_start_preamble` otherwise; follow‑up frames use the
///     driver's response_preamble() (exchange_engine.cpp). Both derive from the same
///     per‑device property, so the flag never promises a wake-up burst the device does not need,
///     with two exceptions. Pairing's directed start frames (0x2C, 0x31, 0x6F) never use a longer
///     preamble than the discovery request the device just answered
///     (PairingEngine::pairing_start_preamble_()). And send_and_receive() may lead a low-power
///     target's tries with the short preamble while the target is believed awake (ADR 0040), with
///     the frame bytes — flag included — unchanged.
 
#include "proto_codecs.h"
#include "proto_constants.h"
#include "proto_device_model.h"
#include "proto_frame.h"
 
namespace esphome {
namespace home_io_control {
 
/// @brief 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).
/// @param f IoFrame to populate.
/// @param own Controller's 3‑byte node ID (source address).
/// @param dst Target device's 3‑byte node ID (destination address).
/// @param low_power True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
/// @param position Desired position 0–100 (0=fully open, 100=fully closed).
/// @return true on success; false if position > 100.
/// @param 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.
bool create_execute_position(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t position,
                             bool silent = false);
 
/// @brief Build a named-command execute frame (0x00) for STOP or a named position.
///
/// The named positions are the entries of NAMED_POSITIONS (proto_device_types.h); 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
///   - PEDESTRIAN: main=0xD8, modifier=0x07 (experimental, gate openers)
///   - PARTIAL:    main=0xD8, modifier=0x09 (garage openers)
///
/// 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, 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.
/// @param f IoFrame to populate.
/// @param own Controller's 3‑byte node ID (source address).
/// @param dst Target device's 3‑byte node ID (destination address).
/// @param low_power True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
/// @param cmd Named command to execute (STOP or a named position).
/// @return true on success; false for invalid/unsupported command.
/// @param silent Use the silent (slower) travel profile. Honoured for FAVORITE only — STOP has no
///        travel speed, and nothing has been captured for the other named positions.
bool create_execute_command(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, CoverCommand cmd,
                            bool silent = false);
 
/// @brief 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.
///
/// @param f IoFrame to populate.
/// @param own Controller's 3‑byte node ID (source address).
/// @param dst Target device's 3‑byte node ID (destination address).
/// @param low_power True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
/// @param 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.
/// @return true on success.
/// @note The elevated-priority override has not yet been confirmed against a real *active*
///       environmental lock.
bool create_force_open(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t open_position);
 
/// @brief Build a position execute frame (0x00) that carries the main parameter only: the 6-byte
/// form `originator, ACEI, MP, MP, 00, 00`, with no functional-parameter block.
///
/// For devices that refuse the block create_execute_position() appends. A Wisniowski / Somfy
/// MOTO 1000 io garage opener answers that block with RESULT_PARAMETER_UNKNOWN before any
/// challenge, accepts a 6-byte STOP, and is opened by its own 1W remote with exactly this shape
/// (`01 43 00 00 00 00`, issue #163). Sent to devices without device_feature::EXTENDED_POSITION_FRAME,
/// and to covers set to TravelSpeed::MOTOR_DEFAULT: a VELUX KLR 200 control pad moves a window with
/// this form, and the window then travels at its own speed rather than at a profile's (ADR 0065).
/// @param f IoFrame to populate.
/// @param own Controller's 3‑byte node ID (source address).
/// @param dst Target device's 3‑byte node ID (destination address).
/// @param low_power True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
/// @param position Target position 0..100 (IO scale: 0 = open, 100 = closed).
/// @param force_open_priority True to send at the force-open ACEI (see create_force_open()) instead
///        of the normal one.
/// @return true on success; false for a position above 100.
bool create_execute_main_parameter(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t position,
                                   bool force_open_priority = false);
 
/// @brief Highest heating level low byte create_execute_heating_level() will frame (the secured level).
static constexpr uint8_t HEATING_LEVEL_MAX = 0x3F;
 
/// @brief Build an EXECUTE (0x00) that sets a heater's heating level.
///
/// The heating level sits in the main parameter (high byte HEATING_LEVEL_MP_PREFIX, low byte the
/// level; see proto_heating_profiles.h). The frame has the eight data bytes a vendor bridge sends with
/// every heating level (corpus `thermor_pilot_wire_interface_exchange_heating_level_execute`, issue #228):
/// ACEI 0xE7, FP11 present in the FP9-FP16 bitmap, FP11 = 0xFFFF. That evidence does not establish what
/// FP11 = 0xFFFF means; it is sent as the bridge sends it.
/// \todo Experimental: no level change has been seen on a heater's display or read back yet, so the
/// frame stays unconfirmed on hardware until a reporter's heater does.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID (source address).
/// @param dst Target device's 3-byte node ID (destination address).
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @param level Heating level low byte (heating_level::*).
/// @return true on success; false for a level above HEATING_LEVEL_MAX.
bool create_execute_heating_level(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t level);
 
/// @brief Build a main-parameter-only EXECUTE (0x00) whose main parameter is a temperature or an alias.
///
/// Same 6-byte shape as create_execute_main_parameter(); the caller encodes the value
/// (encode_temperature_main_parameter(), or heating_prefixed_main_parameter() for an alias).
/// Experimental: unconfirmed on hardware.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID (source address).
/// @param dst Target device's 3-byte node ID (destination address).
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @param main_parameter The 16-bit main parameter.
/// @return true on success.
bool create_execute_heating_main_parameter(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power,
                                           uint16_t main_parameter);
 
/// @brief Build an EXECUTE (0x00) with a temperature or alias main parameter and functional parameter 9.
///
/// Payload: originator, ACEI, MP(2), `00` (no FP1-FP8), `80` (FP9 present), FP9 as two bytes, high
/// byte first (every functional-parameter value is two bytes wide, like the main parameter). FP9
/// carries the active mode (heating_mode_flags::*). No other functional parameter is sent.
/// Experimental: unconfirmed on hardware.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID (source address).
/// @param dst Target device's 3-byte node ID (destination address).
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @param main_parameter The 16-bit main parameter.
/// @param mode_flags FP9 value.
/// @return true on success.
bool create_execute_heating_with_mode_flags(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power,
                                            uint16_t main_parameter, uint16_t mode_flags);
 
/// @brief Build an EXECUTE (0x00) with a temperature or alias main parameter and functional parameter 16.
///
/// Payload: originator, ACEI, MP(2), `00` (no FP1-FP8), `01` (FP16 present, the last bit of the second
/// bitmap), FP16 (two bytes, big-endian like the main parameter). No other functional parameter is sent.
/// Experimental: unconfirmed on hardware.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID (source address).
/// @param dst Target device's 3-byte node ID (destination address).
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @param main_parameter The 16-bit main parameter.
/// @param fp16 FP16 value.
/// @return true on success.
bool create_execute_heating_with_fp16(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power,
                                      uint16_t main_parameter, uint16_t fp16);
 
/// @brief Build a CMD_PRIVATE (0x03) request for an arbitrary function ID.
///
/// 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.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param 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).
/// @param function_id Private function ID (data[0] of the CMD_PRIVATE payload).
/// @param 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.
/// @return true on success.
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 = 0x00);
 
// ============================================================================
// 1W Execute (fire-and-forget class broadcast)
// ============================================================================
//
// 1W has no reply and no challenge: a controller transmits once and the frame either lands or it
// doesn't — there is no ACK to retry on and no 0x3C/0x3D to authenticate through, so the MAC
// inside the payload (create_1w_hmac(), sequence-keyed rather than challenge-keyed) is the only
// authentication a receiving device gets. The destination is a device *class*
// (encode_broadcast_address(), proto_codecs.h), never an individual node — 1W has no addressed
// unicast form at all. Both builders below are pure: they take `sequence` and `controller_key` as
// parameters and neither increment, persist, nor look either up. The sequence store and the
// identity registry that own those concerns (OneWayControllerRegistry, oneway_controller.h)
// arrive in a later step; until then callers are responsible for supplying both.
 
/// @brief Build a 1W position execute frame (CMD 0x00) targeting a device class.
///
/// 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.
/// @param f IoFrame to populate.
/// @param src Our 3-byte controller node address (the 1W controller identity's `node_id`).
/// @param target_type Device class to address; encoded via encode_broadcast_address().
/// @param position Desired position 0–100 (0=fully open, 100=fully closed).
/// @param 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.
/// @param 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.
/// @param 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.
/// @param 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`).
/// @return true on success; false if `position > 100` or if crypto::create_1w_hmac() fails — no
///         partially-populated frame is left behind on failure.
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 = ONEWAY_EXECUTE_ACEI, bool broadcast_all = false);
 
/// @brief Build a 1W named-command execute frame (CMD 0x00) targeting a device class.
///
/// Covers three of CoverCommand's values — STOP, FAVORITE, VENT; PARTIAL and PEDESTRIAN have no 1W
/// encoding and return false like FORCE_OPEN. 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: own captures
/// (tests/corpus/captures/oneway/somfy_smoove_oneway_stop_sx1276.yaml) and the published IV vector
/// (tests/corpus/captures/oneway/reference_1w_oneway_execute_iv_vector.yaml) carry main=0xD2. VENT
/// is not captured anywhere in this project, so main=0xD8/mod=0x03 is assumed. FAVORITE has
/// no support either: main=0xD8/mod=0x00 here is extrapolated purely by analogy with the
/// 2W builder's FAVORITE encoding. 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/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. Its natural encoding would be
/// main=0x64/mod=0x00 — the same bytes this project labels POS_FORCE_OPEN — but 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.
/// 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`.
/// @param f IoFrame to populate.
/// @param src Our 3-byte controller node address (the 1W controller identity's `node_id`).
/// @param target_type Device class to address; encoded via encode_broadcast_address().
/// @param cmd Named command to execute (STOP, FAVORITE, or VENT). CoverCommand::FORCE_OPEN
///        returns false — see the @warning above.
/// @param 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.
/// @param 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.
/// @param acei ACEI byte for payload[1] — see create_1w_execute_position().
/// @param broadcast_all Address `00 00 3F` instead of the typed class — see
///        create_1w_execute_position().
/// @return true on success; false if `cmd` is CoverCommand::FORCE_OPEN (no 1W encoding exists) or
///         if crypto::create_1w_hmac() fails.
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 = ONEWAY_EXECUTE_ACEI, bool broadcast_all = false);
 
// ============================================================================
// 1W Enrollment (CMD 0x30 add-controller / CMD 0x39 remove-controller)
// ============================================================================
//
// Enrollment is the precondition the two builders above assume away: a device obeys a 1W frame
// only from a *registered* controller, so a correctly-keyed, correctly-signed execute from an
// unknown source node is silently ignored (see ADR 0026). These two builders are how a
// controller identity registers itself (0x30) or un-registers (0x39). Like the execute builders,
// both are pure — `sequence` and `controller_key` are parameters, never looked up or persisted —
// and both broadcast to the typed "all" address the same way create_1w_execute_command() does:
// there is no addressed/unicast form, and for a virgin 1W-only device there is usually no address
// to unicast to anyway.
 
/// @brief 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).
///
/// 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 known-answer vector
/// (tests/corpus/captures/enrollment/reference_1w_enrollment_add_controller_kat.yaml,
/// `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`. **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.
///
/// @warning The key-wrap IV comes from `src`, not the destination: a broadcast destination carries
/// no identity, and `src` is the only value that reproduces the published frame this builder is
/// pinned against. That frame's MAC is genuine and verifies, so a missing trailer on real hardware
/// is not evidence that the frame is unauthenticated.
/// @param f IoFrame to populate.
/// @param 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.
/// @param target_type Device class to address; encoded via encode_broadcast_address(). Only
///        devices of this class currently in association mode react.
/// @param manufacturer Manufacturer ID byte to advertise (`man_id`); echoed back verbatim by
///        anything that later decodes this frame with decode_1w_add_controller().
/// @param 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.
/// @param 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.
/// @param 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.
/// @return 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.
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 = true);
 
/// @brief 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 (the `0x39` → `0x30` flow real remotes send)
/// also the prelude OneWayTransmitter::send_enrollment() fires immediately before it.
///
/// Declared payload (9 bytes), shape: `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.
/// @param f IoFrame to populate.
/// @param src Our 3-byte controller node address (the 1W controller identity's `node_id`).
/// @param target_type Device class to address; encoded via encode_broadcast_address().
/// @param 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.
/// @param 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.
/// @return true on success; false if crypto::create_1w_hmac() fails — no partially-populated frame
///         is left behind on failure.
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 get‑status request (0x03). The device responds with its current position.
/// @param f IoFrame to populate.
/// @param own Controller's 3‑byte node ID.
/// @param dst Target device's 3‑byte node ID.
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @return true on success.
bool create_get_status(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power);
 
/// @brief Build a CMD_GET_GENERAL_INFO3 (0x58) request. 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).
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param low_power True if target is battery/solar-powered (sets CTRL1_LOW_POWER).
/// @return true on success.
bool create_general_info3(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power);
 
/// @brief 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`.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param low_power True if target is battery/solar-powered (sets CTRL1_LOW_POWER).
/// @return true on success.
bool create_get_info1(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power);
 
/// @brief 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).
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param low_power True if target is battery/solar-powered (sets CTRL1_LOW_POWER).
/// @return true on success.
bool create_get_info2(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.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param low_power True if target is battery/solar-powered (sets CTRL1_LOW_POWER).
/// @return true on success.
bool create_get_name(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power);
 
/// Build an authenticated set-name request (0x52) using a fixed zero-padded Latin-1 payload.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @param payload Pre-validated fixed payload produced by encode_device_name_payload().
/// @return true on success.
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]);
 
/// @brief Build an authenticated device-identify request (0x1E) that makes a device
/// physically identify itself (brief jog / flash).
///
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID (source address).
/// @param dst Target device's 3-byte node ID (destination address).
/// @param 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.
/// @return true on success.
bool create_identify(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power);
 
/// @brief Build a generic CMD_WRITE_PRIVATE (0x20) frame carrying a caller-supplied payload.
///
/// The single builder behind every heating/climate register read and write (power, setpoint, mode,
/// presence, open-window detection, the measurement and sensor reads). The payload is produced by
/// encode_heating_payload(), encode_heating_read() or encode_heating_write() in proto_heating.h; this
/// builder only frames it. Framing (StartFrame=1, EndFrame=0, Protocol=0) is cross-checked against real
/// Atlantic AGILIA heater writes
/// (tests/corpus/captures/exchange/atlantic_agilia_exchange_setpoint_and_off_read_back.yaml: start,
/// not end). The device answers with CMD_WRITE_PRIVATE_ACK (0x21) after an
/// authenticated 0x3C/0x3D leg the exchange engine handles transparently.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID (source address).
/// @param dst Target device's 3-byte node ID (destination address).
/// @param 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.
/// @param payload Payload bytes (from encode_heating_payload(), encode_heating_read() or encode_heating_write()).
/// @param payload_len Payload length in bytes. Rejected if 0 or > FRAME_MAX_DATA_SIZE.
/// @return true on success; false if payload_len is out of range or set_cmd() fails.
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 an execute‑tilt command (0x00) for slat angle control.
/// @param f IoFrame to populate.
/// @param own Controller node ID.
/// @param dst Target device node ID.
/// @param low_power True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
/// @param 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 with device_feature::TILT will honor this.
/// @return true on success.
bool create_execute_tilt(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t tilt_percent);
 
/// 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.
/// @param f IoFrame to populate.
/// @param own Controller node ID.
/// @param dst Target device node ID.
/// @param low_power True if target is battery/solar‑powered (sets CTRL1_LOW_POWER).
/// @param position Desired position 0–100 (open→closed).
/// @param tilt_percent 0 = fully closed, 100 = fully open.
/// @return true on success; false if position exceeds limits.
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);
 
/// @brief 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: FPI1 bit 5 = FP3,
/// see proto_constants.h) 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.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @param selector Extended-status selector byte (data[1]).
/// @param 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.
/// @param 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.
/// @return true on success.
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 = PRIVATE_GET_POSITION_STATUS);
 
/// Build the status read of the main parameter plus functional parameters: an unauthenticated
/// CMD_PRIVATE (0x03) request with function ID 0x01, the FPI1 bitmap (bit 7 = FP1 ... bit 0 = FP8),
/// one "current value" status type per FPI1 bit, the FPI2 bitmap (bit 7 = FP9 ... bit 0 = FP16) and
/// one status type per FPI2 bit (spec order: each type run follows its bitmap). With the default
/// arguments this is the exact 10 bytes a VELUX KLF 200 gateway sends (public reference: KLF 200
/// API specification v3.18 §10.3.1.4; the same bytes were heard on air from a live KLF 200 at
/// 868 MHz and 2.4 GHz). A non-default FPI2 follows the same layout but has not been seen on air.
/// The reply layout is not decoded here.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @param fpi1 FP1-FP8 bitmap; default requests FP1-FP7.
/// @param fpi2 FP9-FP16 bitmap; default requests none.
/// @return true on success; false (nothing built) when no parameter is requested or more than
///         STATUS_MP_FP_PARAM_COUNT are.
bool create_status_mp_fp_read(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power,
                              uint8_t fpi1 = STATUS_MP_FP_FPI1_MASK, uint8_t fpi2 = STATUS_MP_FP_FPI2);
 
/// Build the read of a device's resulting limitation: an unauthenticated CMD_LIMITATION_STATUS_REQ
/// (0x25) with data `{selector, 0x00, 0x00}`, byte for byte what a VELUX KLF 200 gateway was
/// heard sending (issue #98; public reference: KLF 200 API specification v3.18 section 10.5). The
/// reply's value layout is confirmed under rain on a VELUX window (minimum 93 %); its originator and
/// remaining-time bytes read 00 even then, so they stay unverified. Read-only: the
/// selector is an enum with two values, so this builder cannot produce a limitation write.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param type Which resulting limit to read.
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @return true on success.
bool create_limitation_status_read(IoFrame &f, const uint8_t *own, const uint8_t *dst, LimitationType type,
                                   bool low_power);
 
/// Build a subscribe-to-event request (0x73) for the `subscribe_event` diagnostic probe. The payload
/// is `01 <event hi> <event lo>`. This is the one builder here whose request changes state in the
/// device (a stored subscription), so it accepts only the two allowlisted ids,
/// EVENT_BATTERY_LEVEL_CHANGE and EVENT_LOCAL_SENSOR, and returns false for anything else.
/// \todo The request shape is unconfirmed on hardware: no device has been captured answering it.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param event_id EVENT_BATTERY_LEVEL_CHANGE or EVENT_LOCAL_SENSOR.
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @return true on success, false for an event id outside the allowlist.
bool create_subscribe_event(IoFrame &f, const uint8_t *own, const uint8_t *dst, uint16_t event_id, bool low_power);
 
/// Build an unsubscribe request for the `unsubscribe_event` diagnostic probe: CMD_SUBSCRIBE_EVENT
/// (0x73) with payload `00 <event hi> <event lo>`, the subscribe request with its action byte
/// cleared. Same two-id allowlist as create_subscribe_event().
/// \todo The action value 0x00 is a guess from the frame's shape: no device has been seen to stop
/// reporting after it. It exists to test whether a subscription can be undone.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param event_id EVENT_BATTERY_LEVEL_CHANGE or EVENT_LOCAL_SENSOR.
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @return true on success, false for an event id outside the allowlist.
bool create_unsubscribe_event(IoFrame &f, const uint8_t *own, const uint8_t *dst, uint16_t event_id, bool low_power);
 
/// Build the request that opens a read of one device object (CMD_TRANSFER_OPEN 0x46) for the
/// `read_object` diagnostic probe (ADR 0062). The payload is
/// `<ORIGINATOR_SAAC> <class> 00 <id hi> <id lo> 00 00 00 00`, the form Somfy controllers use to read
/// a whole object; Somfy actuators answered it for class-0 objects (issue #156). Only the class/id pairs
/// in TRANSFER_READABLE_OBJECTS are accepted, so this builder cannot name any other object, and there
/// is no builder for the write twin (0x48).
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param object The class and id to open; must be an entry of TRANSFER_READABLE_OBJECTS.
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @return true on success, false for an object outside the allowlist.
bool create_transfer_open(IoFrame &f, const uint8_t *own, const uint8_t *dst, const TransferObject &object,
                          bool low_power);
 
/// Build the request that reads one chunk of an opened transfer (CMD_UNKNOWN4A_REQ 0x4A):
/// `<handle> <chunk hi> <chunk lo>`, nothing else. Chunk numbers count down from ceil(length/18) to 1;
/// TRANSFER_CHUNK_CLOSE closes the transfer. The payload is fixed at these three bytes, so the write
/// direction of the block (which carries data) cannot be built from here.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param handle Handle byte from the CMD_TRANSFER_OPEN_RESP.
/// @param chunk Chunk number, or TRANSFER_CHUNK_CLOSE.
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @return true on success.
bool create_transfer_read(IoFrame &f, const uint8_t *own, const uint8_t *dst, uint8_t handle, uint16_t chunk,
                          bool low_power);
 
/// Build a tilt‑aware get‑status request (0x03 with extended payload) that returns
/// the 16‑byte tilt block in the response.
/// @param f IoFrame to populate.
/// @param own Controller node ID.
/// @param dst Target device node ID.
/// @param low_power True if the target is a low-power / duty-cycled device (sets CTRL1_LOW_POWER).
/// @return true on success.
bool create_get_status_tilt(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power);
 
/// @brief 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. `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.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst Target device's 3-byte node ID.
/// @param modifier The POS_FAVORITE/POS_VENT_MODIFIER-family selector byte to read back.
/// @param 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).
/// @param low_power True if target is battery/solar-powered (sets CTRL1_LOW_POWER).
/// @return true on success.
bool create_private2_read(IoFrame &f, const uint8_t *own, const uint8_t *dst, uint8_t modifier, bool long_form,
                          bool low_power);
 
/// @brief Build a discovery request with configurable command, destination, and payload.
///
/// 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 the command byte alone, using the nonce as the
/// challenge and the supplied system key.
///
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param command Discovery command code (0x28, 0x2A, or 0x2E).
/// @param dst Destination node ID (broadcast or explicit).
/// @param low_power True to set the LOW_POWER flag in CTRL1.
/// @param ack_capable True to set the ACK flag (CTRL1_ACK) in CTRL1 for this one broadcast. Each
///        caller decides per frame: the `pairing_discovery_ack_capable` tuning knob gates it for
///        Discover & Pair's discovery broadcast (opt-in, default off — see the init_frame()
///        doc in proto_frame.h for why CTRL1_ACK must never become an unconditional default), and
///        the SPE roll-call's low-power frame shape (`CTRL1 = LOW_POWER | ACK`) always passes
///        true.
/// @param payload_enabled True when the optional payload byte is enabled.
/// @param payload Optional payload byte (only used when command requires a payload).
/// @param system_key 16-byte system key; only used for 0x2A HMAC computation.
/// @return true on success; false for unsupported command or missing key for 0x2A.
bool create_discovery_request(IoFrame &f, const uint8_t *own, uint8_t command, const uint8_t *dst, bool low_power,
                              bool ack_capable, bool payload_enabled, uint8_t payload, const uint8_t *system_key);
 
/// Build a discovery broadcast (0x28). Sent to the broadcast address; only devices
/// in pairing mode (PROG button pressed) will respond.
/// @param f IoFrame to populate.
/// @param 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.
/// @return true on success.
bool create_discover(IoFrame &f, const uint8_t *own);
 
/// @brief 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.
///
/// 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.
/// @param f IoFrame to populate.
/// @param own Our advertised (throwaway) node ID — used as both src and the backbone address.
/// @param dst Destination node ID (the discovering hub's real node ID, from its 0x28's src).
/// @param type Device type to advertise.
/// @param subtype Device subtype to advertise.
/// @param manufacturer_id Manufacturer ID to advertise (see MANUFACTURER_* in proto_constants.h).
/// @note The timestamp is a best-effort placeholder copied from a real captured device; see
///       KEY_EXTRACTION_DISCOVER_RESP_TIMESTAMP (proto_commands.cpp).
/// @param flags Multi-information byte to advertise (turnaround class, power-save mode); default
///        KEY_EXTRACTION_DISCOVER_RESP_FLAGS, the `key_extraction_multi_info` tuning value in use.
/// @return true on success.
bool create_discover_resp(IoFrame &f, const uint8_t *own, const uint8_t *dst, DeviceType type, uint8_t subtype,
                          uint8_t manufacturer_id, uint8_t flags = KEY_EXTRACTION_DISCOVER_RESP_FLAGS);
 
/// @brief 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).
///
/// 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.
/// @param f IoFrame to populate.
/// @param own Our advertised (throwaway) node ID.
/// @param dst Destination node ID (the hub that sent the key transfer).
/// @return true on success.
bool create_key_confirm(IoFrame &f, const uint8_t *own, const uint8_t *dst);
 
/// @brief Build a discovery-confirm request (0x2C) — sent by a controller directly to a
/// freshly-discovered device, before proceeding to the key exchange (0x31).
///
/// Every real controller in this project's corpus sends 0x2C between the device's discovery
/// response (0x29) and its own key-init (0x31): KLR200→KUX100
/// (tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml), TaHoma→VELUX SSL
/// (tests/corpus/captures/discovery/velux_ssl_discovery_tahoma_pairing.yaml), and this project's
/// own key-extraction responder answering KIG300/KLR200/KLR300/Somfy TaHoma/Somfy Connectivity
/// Kit (tests/corpus/captures/pairing/velux_kig300_pairing_key_extraction_success.yaml and
/// siblings). Every one of those real hubs sets CTRL1_ACK for an always-alive target (`48 10`) and
/// clears it for a low-power one (`48 20`, CTRL1_LOW_POWER only, no ACK) — see the `ack` param doc
/// for what this builder does with that split. Gated by the `pairing_discover_confirm` tuning knob
/// (`DiscoverConfirmMode::SKIP`/`SEND`/`SEND_WITH_ACK`, tuning_config.h) — `skip` reproduces the
/// sequence without this step: no 0x2C, no post-step pause.
/// @param f IoFrame to populate.
/// @param own Controller's 3-byte node ID.
/// @param dst The freshly-discovered device's 3-byte node ID (from its 0x29's src).
/// @param low_power Set CTRL1_LOW_POWER. See this header's "Low-power flag and preamble
///        handling" note above: unlike most pairing builders, this one is NOT a fixed value —
///        pass the device's own self-reported power-save class from discovery
///        (`pairing::PairingContext::discovery_low_power`).
/// @param ack Set CTRL1_ACK ("sender can handle 2W responses"). The builder is literal — it does
///        not derive `ack` from `low_power` itself; that mirror rule belongs to the caller
///        (`PairingEngine::run_discover_confirm_step_()`), which never asks for `ack` when
///        `low_power` is true. Every corpus hub's own 0x2C sets CTRL1_ACK for an always-alive
///        target (`48 10`) and clears it for a low-power one (`48 20`); this codebase's `send`
///        default instead clears it for an always-alive target too (`48 00`, no corpus hub sends
///        that shape, but a Somfy Izymo dimmer answers it with 0x2D and ignores `48 10`), and
///        `send_with_ack` switches to the hub-observed `48 10`.
/// @return true on success.
bool create_discover_confirm(IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, bool ack);
 
/// @brief 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.
///
/// Device-side only, like create_discover_resp()/create_key_confirm() above. Its controller-role
/// counterpart is create_discover_confirm() just above.
/// 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.
/// @param f IoFrame to populate.
/// @param own Our advertised (throwaway) node ID.
/// @param dst Destination node ID (the hub that sent the discovery confirm).
/// @return true on success.
bool create_discover_confirm_ack(IoFrame &f, const uint8_t *own, const uint8_t *dst);
 
/// @brief Recover the system key from an inbound CMD_KEY_TRANSFER (0x32) payload — the decode
/// counterpart to create_key_transfer()'s encode.
///
/// 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.
/// @param transfer_payload 16-byte CMD_KEY_TRANSFER payload (frame.data).
/// @param 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.
/// @param out_key Output: recovered 16-byte system key.
/// @return true on success (crypt_key() AES failure is the only false case).
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]);
 
/// @brief Build a key transfer request (0x38, "pull") asking a discovered device for its key.
///
/// START set, END clear, CTRL1_LOW_POWER clear, CTRL1 bit 2 (CTRL1_PRIORITY) set: the shape vendor
/// controllers use for this request. An Atlantic AGILIA IO radiator answers it with a CMD_KEY_TRANSFER
/// (0x32) (issue #165); recover_key_from_pull() decrypts that.
/// @param f IoFrame to populate.
/// @param own Controller node ID.
/// @param dst Discovered device node ID.
/// @param challenge 6 random bytes, kept by the caller for the decrypt.
/// @return true on success.
bool create_launch_key_transfer(IoFrame &f, const uint8_t *own, const uint8_t *dst, const uint8_t challenge[HMAC_SIZE]);
 
/// @brief Recover a device's key from the CMD_KEY_TRANSFER (0x32) it sent in answer to our
/// CMD_LAUNCH_KEY_TRANSFER (0x38).
///
/// Same construction as recover_system_key_from_transfer(), with the IV taken from the request
/// that asked for the key: its `data` is the whole request, `{CMD_LAUNCH_KEY_TRANSFER, r0..r5}`, and
/// its challenge the request's 6 bytes. Checked against a documented pull exchange in
/// proto_crypto_test.cpp, and on an Atlantic AGILIA IO radiator, whose 0x3D proved the key (issue #165).
/// @param request Our 0x38, as built by create_launch_key_transfer().
/// @param transfer_payload 16-byte CMD_KEY_TRANSFER payload from the device.
/// @param out_key Output: the device's 16-byte key.
/// @return true on success; false when `request` carries fewer than 6 bytes or AES fails.
bool recover_key_from_pull(const IoFrame &request, const uint8_t transfer_payload[AES_KEY_SIZE],
                           uint8_t out_key[AES_KEY_SIZE]);
 
/// Build a key‑init request (0x31) to start pairing key exchange with a discovered device.
/// @param f IoFrame to populate.
/// @param own Controller node ID.
/// @param dst Discovered device node ID.
/// @return true on success.
bool create_key_init(IoFrame &f, const uint8_t *own, const uint8_t *dst);
 
/// Build a key‑transfer frame (0x32) containing the system key encrypted with the transfer key.
/// @param f IoFrame to populate.
/// @param old_frame The key‑init frame (used to derive the encryption IV).
/// @param dst Target device node ID.
/// @param src Controller node ID.
/// @param key The 16‑byte system key to transfer.
/// @param 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.
/// @return true on success.
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 challenge request (0x3C) containing 6 random bytes. Used when we need to
/// authenticate an incoming request from a device.
/// @param f IoFrame to populate.
/// @param dst Target device node ID (device we're challenging).
/// @param src Controller node ID.
/// @return true on success.
bool create_challenge_req(IoFrame &f, const uint8_t *dst, const uint8_t *src);
 
/// @brief Build a challenge request (0x3C) using a caller-supplied challenge instead of
/// generating a fresh one internally.
///
/// 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.
/// @param f IoFrame to populate.
/// @param dst Target device node ID (device we're challenging).
/// @param src Our own node ID.
/// @param challenge Caller-supplied 6-byte challenge (e.g. from crypto::generate_challenge()).
/// @return true on success.
bool create_challenge_req(IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE]);
 
/// @brief 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).
///
/// 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.
/// @param f IoFrame to populate.
/// @param dst The foreign hub's node ID (from the inbound 0x31's src).
/// @param src Our advertised (throwaway) node ID.
/// @param challenge Caller-supplied 6-byte challenge, retained for the later 0x32 decrypt.
/// @return true on success.
bool create_challenge_req_device_role(IoFrame &f, const uint8_t *dst, const uint8_t *src,
                                      const uint8_t challenge[HMAC_SIZE]);
 
/// Build a challenge response (0x3D) proving we know the system key.
/// HMAC is computed over [original_command_id + original_data] using the challenge.
/// @param f IoFrame to populate.
/// @param dst Target device node ID.
/// @param src Controller node ID.
/// @param challenge 6‑byte challenge from the device.
/// @param origin Original request frame that triggered the challenge.
/// @param 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.
/// @return true on success.
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);
 
/// Compute the 6-byte MAC a challenge response (0x3D) carries for `origin`: create_hmac() over the
/// challenged frame's command byte and payload. Used for our own 0x3D (create_challenge_resp()).
/// @param origin The challenged frame.
/// @param challenge 6-byte challenge from the 0x3C.
/// @param key 16-byte key.
/// @param hmac Output: 6-byte MAC.
/// @return true on success.
bool challenge_resp_hmac(const IoFrame &origin, const uint8_t challenge[HMAC_SIZE], const uint8_t *key,
                         uint8_t hmac[HMAC_SIZE]);
 
/// Check a device's challenge response (0x3D) for `origin`, the frame it sent and we challenged.
/// The device signs its own frame, the same transcript as challenge_resp_hmac().
/// @param origin The device's challenged frame.
/// @param challenge The 6 bytes we sent in the 0x3C.
/// @param mac The 6 bytes of the device's 0x3D.
/// @param key 16-byte key the MAC must verify under.
/// @return true if the MAC matches.
bool verify_challenge_resp(const IoFrame &origin, const uint8_t challenge[HMAC_SIZE], const uint8_t mac[HMAC_SIZE],
                           const uint8_t *key);
 
/// @brief Build a node verification response (0x37) — device side, answering a hub's CMD_NODE_VERIFY_REQ
/// (0x36).
///
/// 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.NodeVerifyRespPayloadMatchesOwnDiscoverRespBackboneAddress
/// (tests/corpus/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/key-extraction.md's "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.
/// @param f IoFrame to populate.
/// @param own Our advertised (throwaway) node ID — used as both src and the payload.
/// @param dst Destination node ID (the hub that sent the node verification request, from its 0x36's src).
/// @return true on success.
bool create_node_verify_resp_device_role(IoFrame &f, const uint8_t *own, const uint8_t *dst);
 
/// @brief 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_NODE_VERIFY_RESP (0x37).
///
/// 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 node-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 the power-save bits of create_discover_resp()'s Multi Information
/// Byte (KEY_EXTRACTION_DISCOVER_RESP_FLAGS), which describe the responder itself — 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.
/// @param f IoFrame to populate.
/// @param dst The hub's node ID (from the inbound 0x3C's src).
/// @param src Our advertised (throwaway) node ID.
/// @param challenge 6-byte challenge from the hub's 0x3C.
/// @param origin Our own preceding CMD_NODE_VERIFY_RESP (0x37) frame — its cmd+data is the transcript.
/// @param key System key (16 bytes).
/// @return true on success.
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 status‑update acknowledgment (0x72). Sent after authenticating a device's
/// status update; broadcast on all 3 channels for reliability.
/// @param f IoFrame to populate.
/// @param own Controller node ID.
/// @param dst Device node ID that sent the update.
/// @return true on success.
bool create_status_update_resp(IoFrame &f, const uint8_t *own, const uint8_t *dst);
 
/// Build a set‑config command (0x6F) telling the device to automatically send
/// status updates when controlled by any remote.
/// @param f IoFrame to populate.
/// @param own Controller node ID.
/// @param 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.
/// @return true on success.
bool create_set_config1(IoFrame &f, const uint8_t *own, const uint8_t *dst);
 
}  // namespace home_io_control
}  // namespace esphome