proto_constants.h

Go to the documentation of this file.

#pragma once
 
/// @file proto_constants.h
/// @brief IO-Homecontrol command IDs, result codes and protocol enumerations.
/// @ingroup hioc_protocol
///
/// Command bytes, CMD_ERROR_RESP result codes, wire position/status flags,
/// cryptographic constants, and the manufacturer/originator/ACEI/discovery
/// lookups. These describe *what* travels on the wire, independent of the
/// frame container (proto_frame.h) and the device model (proto_device_model.h).
 
#include "proto_sizes.h"
 
#include <cstdint>
 
namespace esphome {
namespace home_io_control {
 
// ============================================================================
// Command IDs
// ============================================================================
 
// Normal operation commands
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 =
    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.
static constexpr uint8_t CMD_PRIVATE2_RESP = 0x0D;  ///< Response to CMD_PRIVATE2. See CMD_PRIVATE2's comment.
 
// Priority-level and private register commands
static constexpr uint8_t CMD_PRIORITY_LEVEL_REQ =
    0x19;  ///< Priority-level (lock) query: a one-byte priority level in, the device's lock state
           ///< for that level out (CMD_PRIORITY_LEVEL_RESP). io-homecontrol arbitrates control by
           ///< priority level (0-7), and protective functions such as wind protection hold an
           ///< actuator by locking it at a level. The only capture is
           ///< tests/corpus/captures/exchange/somfy_awning_exchange_priority_level_sx1276.yaml
           ///< (issue #27): a real Somfy TaHoma Switch sends 0x02 and then 0x04 to a Sunea io
           ///< screen it owns, ~212 ms apart. That level-by-level walk fits a lock query and fits
           ///< it better than the "inject sensor value" reading this opcode was once filed under.
           ///< Still a working interpretation: no reply has been captured, so the payload
           ///< semantics are unconfirmed. No builder or dispatch path exists in this codebase.
static constexpr uint8_t CMD_PRIORITY_LEVEL_RESP = 0x1A;  ///< Reply to CMD_PRIORITY_LEVEL_REQ. Never
                                                          ///< observed on the wire.
 
// Device identification
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
 
// Limitation read
static constexpr uint8_t CMD_LIMITATION_STATUS_REQ =
    0x25;  ///< Limitation read: asks a device for its resulting minimum or maximum position limit,
           ///< the value a protective function such as rain protection imposes (CMD_LIMITATION_STATUS_RESP).
           ///< Heard from a VELUX KLF 200 gateway to VELUX windows (issue #98) every five minutes,
           ///< minimum first, then maximum; its purpose follows the KLF 200 API specification v3.18,
           ///< section 10.5 (get limitation / limitation status). The three data bytes are assumed to be
           ///< `[selector] [parameter id] [00]` (see LimitationType); the layout is not yet confirmed
           ///< under an active limitation. Build it with create_limitation_status_read().
static constexpr uint8_t CMD_LIMITATION_STATUS_RESP =
    0x26;  ///< Reply to CMD_LIMITATION_STATUS_REQ. Five data bytes, assumed to be
           ///< `[parameter id] [value hi] [value lo] [originator] [time]`; decode_limitation_status()
           ///< documents the layout. Captured: the unlimited case (0 % and 100 %) and a rain-limited window (minimum
           ///< 93 %, with originator and remaining time both 00).
 
// Discovery and pairing commands
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 =
    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.
static constexpr uint8_t CMD_DISCOVER_SPE_RESP =
    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.
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 =
    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.
static constexpr uint8_t CMD_DISCOVER_ALT_RESP =
    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).
static constexpr uint8_t CMD_ONEWAY_ADD_CONTROLLER =
    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.
static constexpr uint8_t CMD_ONEWAY_REMOVE = 0x39;  ///< 1W "remove controller" (un-pair a 1W remote from a device);
                                                    ///< same payload shape as 0x2E.
 
// Key exchange commands (used during pairing)
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
 
// Node verification and device-initiated key exchange
static constexpr uint8_t CMD_NODE_VERIFY_REQ =
    0x36;  ///< Node verification request: a controller checks that a node belongs to its system.
           ///< The node answers with its address (CMD_NODE_VERIFY_RESP) and the controller then
           ///< challenges that answer, so only a node holding the system key passes. It is what
           ///< closes a key transfer (tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml,
           ///< a Velux KLR200) and what a controller sends to nodes it already knows, with no
           ///< pairing in progress (a Velux KIG300 probing a Somfy dimmer in
           ///< tests/corpus/captures/probe/velux_kig300_probe_capability_burst.yaml; a KLR300
           ///< checking each node after a roll-call in
           ///< tests/corpus/captures/discovery/velux_klr300_discovery_rollcall_node_verification.yaml).
           ///< Answered by the key-extraction responder's create_node_verify_resp_device_role()
           ///< (handle_node_verify_req_() in key_extraction_responder.cpp).
static constexpr uint8_t CMD_NODE_VERIFY_RESP =
    0x37;  ///< Node verification 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. In
           ///< tests/corpus/captures/pairing/velux_kux100_pairing_full.yaml a Velux KLR200 closes
           ///< pairing with 0x36 and then challenges the 0x37 it gets back (see
           ///< CMD_CHALLENGE_REQ). Sent by create_node_verify_resp_device_role()
           ///< (proto_commands.h/.cpp), the key-extraction responder's answer to CMD_NODE_VERIFY_REQ.
static constexpr uint8_t CMD_LAUNCH_KEY_TRANSFER =
    0x38;  ///< Key transfer request ("pull"): a controller asks a device for its system key. Payload
           ///< is 6 random bytes; the device answers with a CMD_KEY_TRANSFER (0x32) holding its key
           ///< under the transfer key, the IV built from {0x38} and those 6 bytes. Sent only by
           ///< `pairing_key_transfer: pull` (create_launch_key_transfer()); not yet seen on air in
           ///< this project's corpus.
 
// Authentication commands (challenge-response for secured commands)
static constexpr uint8_t CMD_CHALLENGE_REQ =
    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_NODE_VERIFY_RESP. The key-extraction responder now answers exactly
           ///< that inbound direction (KeyExtractionResponder::handle_node_verify_challenge_() in
           ///< key_extraction_responder.cpp), so both directions are implemented, not just the outbound
           ///< one.
static constexpr uint8_t CMD_CHALLENGE_RESP =
    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.
 
// File/blob management block (0x48-0x4B)
static constexpr uint8_t CMD_UNKNOWN4A_REQ =
    0x4A;  ///< Reads chunk `<handle><chunk u16>` of a buffer opened by a 0x46/0x47 exchange; seen
           ///< on air between two controllers in a VELUX KLR 200 copy session. What it does to an
           ///< actuator is unknown, and the surrounding 0x46-0x4B block includes write commands.
           ///< 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.
static constexpr uint8_t CMD_UNKNOWN4A_RESP =
    0x4B;  ///< Echoes `<handle><chunk>` followed by up to 18 bytes of data. Observed on the wire
           ///< (tests/corpus/captures/probe/velux_kig300_probe_capability_burst.yaml) answering an
           ///< ON_OFF_SWITCH-type device's traffic; the `01 00 00` payload there has the shape of a
           ///< close echo. Not sent or handled anywhere in this codebase.
 
// Device info commands
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 =
    0x54;  ///< Request device general info 1. Sent by the `get_info1` diagnostic probe
           ///< (docs/diagnostic-probes.md, ADR 0024); field-observed on air from a real hub.
static constexpr uint8_t CMD_GET_INFO1_RESP = 0x55;  ///< 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.
static constexpr uint8_t CMD_GET_INFO2 = 0x56;       ///< 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).
static constexpr uint8_t CMD_GET_INFO2_RESP = 0x57;  ///< Device type/model response
static constexpr uint8_t CMD_GET_GENERAL_INFO3 =
    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.
static constexpr uint8_t CMD_GET_GENERAL_INFO3_RESP =
    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.
 
// Configuration and status update commands
static constexpr uint8_t CMD_SET_CONFIG1 = 0x6F;  ///< Configure device to auto-send status updates
static constexpr uint8_t CMD_SET_CONFIG1_RESP =
    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.
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 =
    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.
static constexpr uint8_t CMD_READ_GROUPS =
    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.
static constexpr uint8_t CMD_REBOOT =
    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.
static constexpr uint8_t CMD_SERVICE_STATUS_ACK = 0xF3;  ///< 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.
 
static constexpr uint8_t CMD_ERROR_RESP = 0xFE;  ///< Error response to any command
 
// === CMD_ERROR_RESP result byte ===
//
// DATA[0] of a CMD_ERROR_RESP packs a result code into bits [7:3] and an execution state into
// bits [2:0]: byte = (code << 3) | state. Our captures fit this layout: every corpus 0xFE byte
// but one has state 0, a device answers a command it does not implement with 0x08 = code 1
// "command unknown" (tests/corpus/captures/probe/somfy_awning_probe_general_info3_lr1121.yaml,
// velux_window_probe_metadata_replies.yaml, velux_kig300_probe_capability_burst.yaml), and a
// priority lock comes back as 0x38 = code 7 (tests/corpus/captures/exchange/
// tilt_cover_exchange_priority_locked_error.yaml). The RESULT_* values below that are multiples
// of 8 (RESULT_COMMAND_UNKNOWN .. RESULT_ALREADY_CONFIGURED) are those codes already shifted into
// place. The run-status values with state bits set (0x01-0x24) and the limitation values
// (0xDF-0xEE) stay as a fallback: one Somfy capture does answer with 0x05
// (tests/corpus/captures/identify/somfy_awning_identify_wrong_systemkey_sx1276.yaml), so not
// every device uses the packed form.
static constexpr uint8_t ERROR_RESP_CODE_SHIFT = 3;     ///< Result code sits in bits [7:3] of the 0xFE byte.
static constexpr uint8_t ERROR_RESP_STATE_MASK = 0x07;  ///< Execution state sits in bits [2:0] of the 0xFE byte.
static constexpr uint8_t ERROR_RESP_CODE_MAX = 0x11;    ///< Highest named result code (17, "already configured").
 
// Command-result / limitation codes carried in CMD_ERROR_RESP DATA[0].
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_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_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_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_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.
// Packed result codes (code << 3, state 0 = "non executing"); see the block comment above.
static constexpr uint8_t RESULT_COMMAND_UNKNOWN = 0x08;  ///< Code 1: the device does not offer this command in its
                                                         ///< current state or class.
static constexpr uint8_t RESULT_MODE_OR_STATE_UNKNOWN = 0x10;  ///< Code 2: mode or state number unknown.
static constexpr uint8_t RESULT_BAD_MAC = 0x18;                ///< Code 3: challenge answer (MAC) did not verify.
static constexpr uint8_t RESULT_SETUP_REQUIRED = 0x20;         ///< Code 4: the device needs setting up first.
static constexpr uint8_t RESULT_PARAMETER_UNKNOWN = 0x28;      ///< Code 5: parameter, alias, access method or scenario
                                                               ///< unknown. The Somfy Izymo answers our SetConfig1
                                                               ///< (0x6F) with it during pairing.
static constexpr uint8_t RESULT_ORIGINATOR_DISABLED = 0x30;    ///< Code 6: command originator disabled.
static constexpr uint8_t RESULT_PRIORITY_LOCKED = 0x38;        ///< Code 7: priority locked; the command's priority
                                                               ///< level is too low to run.
static constexpr uint8_t RESULT_PRIORITY_SERVICE_NOT_SUPPORTED = 0x40;   ///< Code 8: priority service not supported.
static constexpr uint8_t RESULT_PARAMETER_LIMITATION_ADJUSTMENT = 0x48;  ///< Code 9: parameter limitation adjustment.
static constexpr uint8_t RESULT_PARAMETER_INCOHERENCE_ADJUSTMENT =
    0x50;                                                    ///< Code 10: parameter incoherence adjustment.
static constexpr uint8_t RESULT_TOTAL_INCOHERENCE = 0x58;    ///< Code 11: the request does not fit what the device
                                                             ///< implements. Seen cross-vendor (Somfy Sunea awning +
                                                             ///< dimmer, Velux window) when a diagnostic probe walks
                                                             ///< past the last supported function index or block.
static constexpr uint8_t RESULT_SERVICE_FULL = 0x60;         ///< Code 12: service full.
static constexpr uint8_t RESULT_ALIAS_INCOHERENCE = 0x68;    ///< Code 13: alias incoherence.
static constexpr uint8_t RESULT_SESSION_INTERRUPTED = 0x70;  ///< Code 14: session interrupted.
static constexpr uint8_t RESULT_NOT_IMPLEMENTED = 0x78;      ///< Code 15: not implemented.
static constexpr uint8_t RESULT_COMMAND_REJECTED = 0x80;     ///< Code 16: command rejected. A Somfy Sunilus and a
                                                             ///< Somfy J406io answered a key transfer (0x32) with it.
static constexpr uint8_t RESULT_ALREADY_CONFIGURED = 0x88;   ///< Code 17: already configured.
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.
 
// ============================================================================
// Position and Status Wire Constants
// ============================================================================
 
/// 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.
static constexpr uint8_t POS_STOP = 0xD2;      ///< Wire value: stop movement.
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.
 
/// Offset of the main position/command byte in a CMD_EXECUTE payload — after the originator (first
/// byte) and the ACEI (second byte). Holds a 0-100 position scale value or one of the POS_* codes.
static constexpr uint8_t EXECUTE_MAIN_BYTE_OFFSET = 2;
 
/// @brief 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.
static constexpr uint8_t POS_SECURED_TARGET = 0xD1;
 
/// @brief Wire value for the default position command.
///
/// Moves the actuator to its factory or user-configured default position.
static constexpr uint8_t POS_DEFAULT = 0xD3;
 
/// @brief 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.
static constexpr uint8_t POS_FORCE_OPEN = 0x64;
 
/// @brief 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.
static constexpr uint8_t POS_VENT_MODIFIER = 0x03;
 
/// @brief 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.
static constexpr uint8_t POSITION_WIRE_SCALE = 2;
/// @brief 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.
static constexpr uint8_t POSITION_WIRE_MAX = 200;
 
/// Status byte flags in CMD_PRIVATE_RESP and CMD_STATUS_UPDATE.
static constexpr uint8_t STATUS_STOPPED = 0x01;   ///< Byte 0 bit 0: device is not moving
static constexpr uint8_t STATUS_EXPECTED = 0x80;  ///< Byte 1 bit 7: device will send auto status update
/// Byte 1 bits 5-6: the device's coarse battery level (BatteryState). Every solar Somfy actuator
/// captured reports 3 here and every mains one 0 (tests/corpus/captures/statuspoll/
/// somfy_rs100_statuspoll_kig300_sx1276.yaml, somfy_oximo40_statuspoll_sx1262.yaml,
/// somfy_awning_statuspoll_success_sx1262.yaml).
static constexpr uint8_t STATUS_BATTERY_MASK = 0x60;
static constexpr uint8_t STATUS_BATTERY_SHIFT = 5;  ///< Right shift that brings STATUS_BATTERY_MASK down to 0-3.
static constexpr uint8_t STATUS_TILT_SELECTOR =
    0x20;  ///< Extended status payload marker for tilt-capable devices: FPI1 with bit 5 set = functional parameter
           ///< FP3 (FPI1 bit 7 = FP1 ... bit 0 = FP8). The actuator echoes FPI1/FPI2 in its ack (VELUX KLF 200 API
           ///< v3.18 §10.1.1.5). The 0x80 form of the extended 0x03 request selects FP1.
 
/// @brief 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.
static constexpr uint8_t PRIVATE_GET_POSITION_STATUS = 0x03;
 
/// @name CMD_PRIVATE status read of the main parameter plus functional parameters (MP + FP1-FP7)
/// The payload create_status_mp_fp_read() sends is a replay of the status read a VELUX KLF 200
/// gateway sends to its devices (KLF 200 API specification v3.18 §10.3.1.4: status type 1 =
/// current position, FPI1 selecting FP1-FP7). The bytes are on-air evidence, not a decoded
/// request: the reply layout is not interpreted by this codebase.
/// @{
static constexpr uint8_t PRIVATE_STATUS_MP_FP = 0x01;     ///< CMD_PRIVATE function ID at data[0].
static constexpr uint8_t STATUS_MP_FP_FPI1_MASK = 0xFE;   ///< FPI1: FP1..FP7 requested (bit 7 = FP1 ... bit 1 = FP7).
static constexpr uint8_t STATUS_MP_FP_PARAM_TYPE = 0x01;  ///< Status type per requested parameter: current value.
static constexpr uint8_t STATUS_MP_FP_PARAM_COUNT = 7;    ///< FP1-FP7: the most one request can select.
static constexpr uint8_t STATUS_MP_FP_FPI2 = 0x00;        ///< FPI2: no FP9-FP16 requested.
/// @}
 
/// @name Limitation read (CMD_LIMITATION_STATUS_REQ / CMD_LIMITATION_STATUS_RESP)
/// The layout is a hypothesis built from frames a VELUX KLF 200 was heard sending (issue #98) and
/// the KLF 200 API specification v3.18, section 10.5 (get limitation: parameter id and limitation
/// type, 0 = resulting minimum, 1 = resulting maximum). Confirm it against a reply captured under
/// an active limitation before building on it.
/// @{
 
/// On-air selector byte (request data[0]) choosing which resulting limit to read. Exactly two
/// values exist on purpose: the same opcode probably also carries the limitation write of section
/// 10.5.2, so no other selector may be constructible. The minimum/maximum assignment rests on
/// request order only (the minimum read always came first, with 0x80).
enum class LimitationType : uint8_t {
  MINIMUM = 0x80,  ///< Resulting minimum limit; rain protection raises it (a floor on the position value).
  MAXIMUM = 0xC0,  ///< Resulting maximum limit.
};
 
static constexpr uint8_t LIMITATION_PARAM_MP = 0x00;     ///< Parameter id of the main parameter.
static constexpr uint8_t LIMITATION_PARAM_FP_FIRST = 1;  ///< Parameter id of FP1.
static constexpr uint8_t LIMITATION_PARAM_FP_LAST = 16;  ///< Parameter id of FP16.
static constexpr uint8_t LIMITATION_REQ_DATA_SIZE = 3;   ///< Request data: selector, parameter id, 0x00.
static constexpr uint8_t LIMITATION_RESP_DATA_SIZE = 5;  ///< Reply data: parameter id, value (2), originator, time.
 
/// Remaining-time codes of a limitation reply's last byte (KLF 200 API specification v3.18, table
/// 200): codes 0-252 count `(n + 1) * 30` seconds, 253 means no time limit, and 254/255 are the
/// timer values the set command uses to delete an entry (never a duration).
static constexpr uint8_t LIMITATION_TIME_MAX_COUNTED = 252;  ///< Highest code that encodes a duration.
static constexpr uint8_t LIMITATION_TIME_UNLIMITED = 253;    ///< Limitation without a time limit.
static constexpr uint32_t LIMITATION_TIME_STEP_S = 30;       ///< Seconds per time-code step.
/// @}
 
// ============================================================================
// Cryptographic Constants
// ============================================================================
 
/// 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.
static constexpr uint8_t TRANSFER_KEY[AES_KEY_SIZE] = {0x34, 0xC3, 0x46, 0x6E, 0xD8, 0x8F, 0x4E, 0x8E,
                                                       0x16, 0xAA, 0x47, 0x39, 0x49, 0x88, 0x43, 0x73};
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
 
/// Broadcast address for device discovery (0x00003B).
/// Used as destination in CMD_DISCOVER_REQ frames to trigger all pairable devices to respond.
static constexpr uint8_t BROADCAST_DISCOVER[NODE_ID_SIZE] = {0x00, 0x00, 0x3B};
 
/// 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).
static constexpr uint8_t BROADCAST_DISCOVER_ALT[NODE_ID_SIZE] = {0x00, 0x00, 0x3F};
 
// ============================================================================
// Command Name Lookup
// ============================================================================
 
/// @brief 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".
/// @param cmd Command byte from the frame header.
/// @return Null-terminated string.
const char *command_name(uint8_t cmd);
 
// ============================================================================
// Manufacturer ID Lookup
// ============================================================================
 
/// @brief Maximum manufacturer ID with a known name in the lookup table.
static constexpr uint8_t MANUFACTURER_ID_MAX = 12;
 
/// @brief 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.
/// @{
static constexpr uint8_t MANUFACTURER_VELUX = 1;            ///< VELUX (roof windows, skylights).
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).
/// @}
 
/// @brief 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`, `hub_validators.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.
/// @param id Manufacturer ID byte (1–12 for known manufacturers).
/// @return Null-terminated lowercase string such as "unknown", or mixed-case name like "Somfy".
const char *manufacturer_name(uint8_t id);
 
// ============================================================================
// Command Originator Codes
// ============================================================================
 
/// @brief 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.
/// @{
static constexpr uint8_t ORIGINATOR_LOCAL_USER = 0x00;        ///< User pressed a button on the actuator.
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).
/// @}
 
/// @brief Get a human-readable name for a command originator byte.
///
/// @param originator Originator code from the first data byte of CMD_EXECUTE.
/// @return Null-terminated string such as "rain_sensor" or "user_remote".
const char *originator_name(uint8_t originator);
 
// ============================================================================
// ACEI (Application Command Execution Interface)
// ============================================================================
 
/// @brief 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).
/// @{
static constexpr uint8_t ACEI_VALID_BIT = 0x01;      ///< Bit 0: command validity flag.
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.
/// @}
 
/// @brief ACEI priority level values (0–7).
///
/// These values are extracted from the ACEI byte via (acei & ACEI_LEVEL_MASK) >> ACEI_LEVEL_SHIFT.
/// @{
static constexpr uint8_t ACEI_LEVEL_PROTECTION_HUMAN = 0;   ///< Personal safety (highest, overrides all).
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).
/// @}
 
/// @brief 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.
/// @param level Priority level value (0–7).
/// @return Null-terminated string such as "user_default" or "protection_sensor".
const char *acei_level_name(uint8_t level);
 
/// @brief 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.
static constexpr uint8_t ONEWAY_EXECUTE_ACEI =
    (ACEI_LEVEL_USER_HIGH << ACEI_LEVEL_SHIFT) | (1 << ACEI_EXTENDED_SHIFT) | ACEI_VALID_BIT;
 
/// @brief 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.
static constexpr uint8_t ONEWAY_EXECUTE_ACEI_VELUX = (ACEI_LEVEL_USER_DEFAULT << ACEI_LEVEL_SHIFT) | ACEI_VALID_BIT;
 
// ============================================================================
// Discovery Response Extended Fields
// ============================================================================
 
/// @brief 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.
/// @{
static constexpr uint8_t DISCOVERY_RESP_BACKBONE_OFFSET = 2;      ///< Backbone address starts at data[2] (3 bytes);
                                                                  ///< cross-confirmed by CMD_NODE_VERIFY_RESP (0x37),
                                                                  ///< which returns the same 3 bytes for the same
                                                                  ///< device (see that constant's comment).
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.
/// @}
 
// === Multi Information Byte (Discovery Response data[6]) ===
// The flags byte in the discovery response encodes device capabilities and timing
// characteristics that help a controller tune its interaction with the actuator.
 
/// @brief Bit masks and shifts for the Multi Information Byte fields.
/// @{
static constexpr uint8_t DISCOVERY_FLAGS_ATT_MASK = 0xC0;       ///< Bits [7:6]: actuator turnaround time class.
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: 1 = the node has its own RF, 0 = it sits on a wired backbone only (VELUX KLF 200 API
           ///< v3.18 §7.4.1.2.4-7, Table 52).
static constexpr uint8_t DISCOVERY_FLAGS_IO_MEMBERSHIP =
    0x04;  ///< Bit 2: io-homecontrol membership; always 1 (same table).
static constexpr uint8_t DISCOVERY_FLAGS_POWER_SAVE_MASK = 0x03;  ///< Bits [1:0]: power save mode.
/// @}
 
/// @brief Actuator Turnaround Time (ATT) class values.
///
/// The time within which each node must respond after receiving a command (VELUX KLF 200 API
/// v3.18 §7.4.1.2.4-7, Table 51: "Actuator Turnaround time"). The unit is milliseconds.
/// Extracted from the Multi Information Byte via
/// `(flags & DISCOVERY_FLAGS_ATT_MASK) >> DISCOVERY_FLAGS_ATT_SHIFT`.
/// @{
static constexpr uint8_t ATT_CLASS_5MS = 0;   ///< Response within 5 ms.
static constexpr uint8_t ATT_CLASS_10MS = 1;  ///< Response within 10 ms.
static constexpr uint8_t ATT_CLASS_20MS = 2;  ///< Response within 20 ms.
static constexpr uint8_t ATT_CLASS_40MS = 3;  ///< Response within 40 ms.
/// @}
 
/// @brief 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.
/// @{
static constexpr uint8_t POWER_SAVE_ALWAYS_ALIVE = 0;  ///< Device is always listening — short preamble works.
static constexpr uint8_t POWER_SAVE_LOW_POWER = 1;     ///< Device sleeps — needs long preamble to wake.
/// @}
 
/// @brief Extract the ATT class field from a discovery response's Multi Information Byte.
/// @param flags Multi Information Byte (data[DISCOVERY_RESP_FLAGS_OFFSET]).
/// @return ATT class value (0–3); pass to att_class_name() for a human-readable string.
inline uint8_t discovery_att_class(uint8_t flags) {
  return (flags & DISCOVERY_FLAGS_ATT_MASK) >> DISCOVERY_FLAGS_ATT_SHIFT;
}
 
/// @brief Extract the power save mode field from a discovery response's Multi Information Byte.
/// @param flags Multi Information Byte (data[DISCOVERY_RESP_FLAGS_OFFSET]).
/// @return Power save mode value (0–1); pass to power_save_mode_name() for a human-readable string.
inline uint8_t discovery_power_save_mode(uint8_t flags) { return flags & DISCOVERY_FLAGS_POWER_SAVE_MASK; }
 
/// @brief Get a human-readable turnaround time string for an ATT class value.
/// @param att_class ATT class (0–3) extracted from the Multi Information Byte.
/// @return Null-terminated string such as "5ms", "10ms", "20ms", or "40ms".
const char *att_class_name(uint8_t att_class);
 
/// @brief Get a human-readable power save mode name.
/// @param mode Power save value (0–1) extracted from the Multi Information Byte.
/// @return Null-terminated string such as "always_alive" or "low_power".
const char *power_save_mode_name(uint8_t mode);
 
// ============================================================================
// Command Result Codes
// ============================================================================
 
/// @brief Result code (bits [7:3]) of a CMD_ERROR_RESP byte.
/// @param result Result byte from CMD_ERROR_RESP data[0].
/// @return Code 0..31; codes 1..ERROR_RESP_CODE_MAX are named (see the RESULT_* block).
constexpr uint8_t error_resp_code(uint8_t result) { return result >> ERROR_RESP_CODE_SHIFT; }
 
/// @brief Execution state (bits [2:0]) of a CMD_ERROR_RESP byte.
/// @param result Result byte from CMD_ERROR_RESP data[0].
/// @return State 0..7; 0 means the command was not executed.
constexpr uint8_t error_resp_state(uint8_t result) { return result & ERROR_RESP_STATE_MASK; }
 
/// @brief Return a stable symbolic name for a CMD_ERROR_RESP result code.
///
/// A byte with state 0 and a named code reads as a packed result code (RESULT_COMMAND_UNKNOWN ..
/// RESULT_ALREADY_CONFIGURED); every other byte is looked up in the run-status / limitation table.
/// @param result Result byte from CMD_ERROR_RESP data[0].
/// @return Uppercase symbolic name, or "UNKNOWN_RESULT_CODE" when unmapped.
const char *command_result_name(uint8_t result);
/// @brief Return a human-readable explanation for a CMD_ERROR_RESP result code.
/// @param result Result byte from CMD_ERROR_RESP data[0].
/// @return Short description suitable for warn-level logs.
const char *command_result_description(uint8_t result);
/// @brief Check whether a result code represents an environmental or control limitation.
/// @param result Result byte from CMD_ERROR_RESP data[0].
/// @return true when the response reports a limitation rather than a generic execution error.
bool is_limitation_result(uint8_t result);
 
}  // namespace home_io_control
}  // namespace esphome