Home IO Control
ESPHome add-on for IO-Homecontrol devices
Loading...
Searching...
No Matches
proto_commands.h File Reference
Architecture Layers » Protocol Layer

Command builders for the IO‑Homecontrol protocol. More...

#include "proto_codecs.h"
#include "proto_constants.h"
#include "proto_device_model.h"
#include "proto_frame.h"
Include dependency graph for proto_commands.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Namespaces

namespace  esphome
namespace  esphome::home_io_control

Functions

bool esphome::home_io_control::create_execute_position (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t position, bool silent)
 Build a position execute command (0x00) to move a device to a numeric position.
bool esphome::home_io_control::create_execute_command (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, CoverCommand cmd, bool silent)
 Build a named-command execute frame (0x00) for STOP, FAVORITE, or VENT.
bool esphome::home_io_control::create_force_open (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t open_position)
 Build a force-open execute frame (0x00): an ordinary position command to the device's wire-scale "fully open" value, sent at elevated ACEI priority (see EXECUTE_ACEI_FORCE_OPEN).
bool esphome::home_io_control::create_execute_main_parameter (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t position, bool force_open_priority)
 Build a main-parameter-only position execute frame (0x00). See proto_commands.h.
bool esphome::home_io_control::create_execute_heating_level (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t level)
 Build a heating-level execute frame (0x00). See proto_commands.h.
bool esphome::home_io_control::create_execute_heating_main_parameter (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint16_t main_parameter)
 Build a temperature / alias execute frame (0x00), main parameter only. See proto_commands.h.
bool esphome::home_io_control::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)
 Build a temperature / alias execute frame (0x00) carrying functional parameter 9. See proto_commands.h.
bool esphome::home_io_control::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)
 Build a temperature / alias execute frame (0x00) carrying functional parameter 16. See proto_commands.h.
bool esphome::home_io_control::create_private_function (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t function_id, uint8_t sub_index)
 Build a CMD_PRIVATE (0x03) request for an arbitrary function ID.
bool esphome::home_io_control::create_1w_execute_position (IoFrame &f, const uint8_t src[NODE_ID_SIZE], DeviceType target_type, uint8_t position, uint16_t sequence, const uint8_t controller_key[AES_KEY_SIZE], uint8_t acei, bool broadcast_all)
 Build a 1W position execute frame (CMD 0x00) targeting a device class.
bool esphome::home_io_control::create_1w_execute_command (IoFrame &f, const uint8_t src[NODE_ID_SIZE], DeviceType target_type, CoverCommand cmd, uint16_t sequence, const uint8_t controller_key[AES_KEY_SIZE], uint8_t acei, bool broadcast_all)
 Build a 1W named-command execute frame (CMD 0x00) targeting a device class.
bool esphome::home_io_control::create_1w_add_controller (IoFrame &f, const uint8_t src[NODE_ID_SIZE], DeviceType target_type, uint8_t manufacturer, uint16_t sequence, const uint8_t controller_key[AES_KEY_SIZE], bool with_mac)
 Build a 1W add-controller frame (CMD 0x30).
bool esphome::home_io_control::create_1w_remove_controller (IoFrame &f, const uint8_t src[NODE_ID_SIZE], DeviceType target_type, uint16_t sequence, const uint8_t controller_key[AES_KEY_SIZE])
 Build a 1W remove-controller frame (CMD 0x39).
bool esphome::home_io_control::create_get_status (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
 Build a get-status request (0x03). The device responds with its current position.
bool esphome::home_io_control::create_general_info3 (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
 Build a CMD_GET_GENERAL_INFO3 (0x58) request.
bool esphome::home_io_control::create_get_info1 (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
 Build a CMD_GET_INFO1 (0x54) request. No payload. See proto_commands.h for the evidence note.
bool esphome::home_io_control::create_get_info2 (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
 Build a CMD_GET_INFO2 (0x56) request. No payload. See proto_commands.h for the evidence note.
bool esphome::home_io_control::create_get_name (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
 Build a get-name request (0x50).
bool esphome::home_io_control::create_set_name (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, const uint8_t payload[DEVICE_NAME_WRITE_PAYLOAD_SIZE])
 Build an authenticated set-name request (0x52) using a fixed zero-padded Latin-1 payload.
bool esphome::home_io_control::create_identify (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
 Build an authenticated device-identify request (0x1E).
bool esphome::home_io_control::create_write_private (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, const uint8_t *payload, size_t payload_len)
 Build a generic CMD_WRITE_PRIVATE (0x20) frame around a caller-supplied payload — the one builder behind every heating/climate function.
bool esphome::home_io_control::create_execute_tilt (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t tilt_percent)
 Build a tilt execute command (0x00) for devices that support slat angle control.
bool esphome::home_io_control::create_execute_position_and_tilt (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t position, uint8_t tilt_percent)
 Build a combined position-and-tilt execute command (0x00) — setClosureAndOrientation.
bool esphome::home_io_control::create_get_status_extended (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, uint8_t selector, uint8_t block, uint8_t function_id)
 Build an extended CMD_PRIVATE (0x03) request with a selector/block pair — the shape real hubs use for both the tilt block (selector STATUS_TILT_SELECTOR) and the field-observed selector 0x80 (tests/corpus/captures/probe/multi_somfy_probe_extended_private_both_selectors.yaml), which this codebase has never decoded.
bool esphome::home_io_control::create_status_mp_fp_read (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
 Build the KLF-style status read of the main parameter plus FP1-FP7 (see the header for the evidence).
bool esphome::home_io_control::create_limitation_status_read (IoFrame &f, const uint8_t *own, const uint8_t *dst, LimitationType type, bool low_power)
 Build the limitation read (see the header for the evidence and the read-only guarantee).
bool esphome::home_io_control::create_get_status_tilt (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power)
 Build a tilt-aware get-status request (0x03) that returns the extended 16-byte tilt payload.
bool esphome::home_io_control::create_private2_read (IoFrame &f, const uint8_t *own, const uint8_t *dst, uint8_t modifier, bool long_form, bool low_power)
 Build a CMD_PRIVATE2 (0x0C) request in either of the two field-observed shapes.
bool esphome::home_io_control::create_discovery_request (IoFrame &f, const uint8_t *own, uint8_t command, const uint8_t *dst, bool low_power, bool ack_capable, bool payload_enabled, uint8_t payload, const uint8_t *system_key)
 Build a configurable discovery request command (0x28, 0x2A, or 0x2E).
bool esphome::home_io_control::create_discover (IoFrame &f, const uint8_t *own)
 Build a discovery broadcast (0x28).
bool esphome::home_io_control::create_discover_resp (IoFrame &f, const uint8_t *own, const uint8_t *dst, DeviceType type, uint8_t subtype, uint8_t manufacturer_id)
 Build a discovery response (0x29) — device side, used only by the key-extraction responder.
bool esphome::home_io_control::create_key_confirm (IoFrame &f, const uint8_t *own, const uint8_t *dst)
 Build a key-confirm frame (0x33) — device side, used only by the key-extraction responder.
bool esphome::home_io_control::create_discover_confirm (IoFrame &f, const uint8_t *own, const uint8_t *dst, bool low_power, bool ack)
 Build a discovery-confirm request (0x2C) — controller side, sent directly to a freshly-discovered device before the key exchange.
bool esphome::home_io_control::create_discover_confirm_ack (IoFrame &f, const uint8_t *own, const uint8_t *dst)
 Build a discovery-confirm acknowledgement (0x2D) — device side, used only by the key-extraction responder.
bool esphome::home_io_control::recover_system_key_from_transfer (const uint8_t transfer_payload[AES_KEY_SIZE], const uint8_t challenge[HMAC_SIZE], uint8_t out_key[AES_KEY_SIZE])
 Recover the system key from a CMD_KEY_TRANSFER payload.
bool esphome::home_io_control::create_launch_key_transfer (IoFrame &f, const uint8_t *own, const uint8_t *dst, const uint8_t challenge[HMAC_SIZE])
 Build a key transfer request (0x38). See proto_commands.h for the frame shape.
bool esphome::home_io_control::recover_key_from_pull (const IoFrame &request, const uint8_t transfer_payload[AES_KEY_SIZE], uint8_t out_key[AES_KEY_SIZE])
 Recover a device's key from its answer to our 0x38.
bool esphome::home_io_control::create_key_init (IoFrame &f, const uint8_t *own, const uint8_t *dst)
 Build a key-init request (0x31) to start the pairing key exchange with a discovered device.
bool esphome::home_io_control::create_key_transfer (IoFrame &f, IoFrame &old_frame, const uint8_t *dst, const uint8_t *src, const uint8_t key[AES_KEY_SIZE], const uint8_t challenge[HMAC_SIZE])
 Build a key-transfer frame (0x32) containing the system key encrypted with the transfer key.
bool esphome::home_io_control::create_challenge_req (IoFrame &f, const uint8_t *dst, const uint8_t *src)
 Build a challenge request (0x3C) containing 6 random bytes.
bool esphome::home_io_control::create_challenge_req (IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE])
 Build a challenge request (0x3C) using a caller-supplied challenge.
bool esphome::home_io_control::create_challenge_req_device_role (IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE])
 Build a device-role challenge request (0x3C) — device side, used only by the key-extraction responder.
bool esphome::home_io_control::create_challenge_resp (IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE], const IoFrame &origin, const uint8_t *key)
 Build a challenge response (0x3D) proving we know the system key.
bool esphome::home_io_control::challenge_resp_hmac (const IoFrame &origin, const uint8_t challenge[HMAC_SIZE], const uint8_t *key, uint8_t hmac[HMAC_SIZE])
 The 0x3D MAC for origin.
bool esphome::home_io_control::verify_challenge_resp (const IoFrame &origin, const uint8_t challenge[HMAC_SIZE], const uint8_t mac[HMAC_SIZE], const uint8_t *key)
 Check a device's 0x3D for origin, in constant time (crypto::verify_hmac()).
bool esphome::home_io_control::create_node_verify_resp_device_role (IoFrame &f, const uint8_t *own, const uint8_t *dst)
 Build an address response (0x37) — device side, used only by the key-extraction responder.
bool esphome::home_io_control::create_challenge_resp_device_role (IoFrame &f, const uint8_t *dst, const uint8_t *src, const uint8_t challenge[HMAC_SIZE], const IoFrame &origin, const uint8_t *key)
 Build a device-role challenge response (0x3D) — device side, used only by the key-extraction responder answering a hub-issued 0x3C challenging our own 0x37.
bool esphome::home_io_control::create_status_update_resp (IoFrame &f, const uint8_t *own, const uint8_t *dst)
 Build a status-update acknowledgment (0x72).
bool esphome::home_io_control::create_set_config1 (IoFrame &f, const uint8_t *own, const uint8_t *dst)
 Build a set-config command (0x6F) to tell the device to automatically send status updates when controlled by any remote (not just us).

Variables

static constexpr uint8_t esphome::home_io_control::HEATING_LEVEL_MAX = 0x3F
 Highest heating level low byte create_execute_heating_level() will frame (the secured level).

Detailed Description

Command builders for the IO‑Homecontrol 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.
  • 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.

Definition in file proto_commands.h.