proto_commands.h File Reference

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

#include "proto_codecs.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)
	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)
	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_get_status (IoFrame &f, const uint8_t *own, const uint8_t *dst)
	Build a get-status request (0x03). The device responds with its current position.
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, 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)
	Build an authenticated device-identify request (0x1E).
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_tilt (IoFrame &f, const uint8_t *own, const uint8_t *dst)
	Build a tilt-aware get-status request (0x03) that returns the extended 16-byte tilt payload.
bool	esphome::home_io_control::create_discovery_request (IoFrame &f, const uint8_t *own, uint8_t command, const uint8_t *dst, bool low_power, bool payload_enabled, uint8_t payload, const uint8_t *system_key)
	Build a configurable discovery request command (0x28, 0x2A, or 0x2E).
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_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_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::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).

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:

• Every frame addressed to a specific device sets CTRL1_LOW_POWER: the codebase does not track per‑device power class, battery/solar devices need the flag on every frame sent to them, and the golden‑frame corpus shows real devices accepting it.
• The flag does not select the TX preamble. The exchange engine picks the preamble from frame position: start frames use LONG_PREAMBLE (1024 bytes) so a sleeping receiver can wake, follow‑up frames use the driver's response_preamble() (exchange_engine.cpp).

Definition in file proto_commands.h.