proto_frame.h File Reference

IO-Homecontrol 2W frame container: control bytes, IoFrame and (de)serialization. More...

#include "proto_sizes.h"
#include <cstdint>
#include <cstring>
#include <string>

Include dependency graph for proto_frame.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	esphome::home_io_control::IoFrame
	Parsed IO‑Homecontrol frame (CTRL0/1 + addresses + command + data). More...

Namespaces
namespace	esphome
namespace	esphome::home_io_control

Functions
void	esphome::home_io_control::init_frame (IoFrame &f, bool is_2w=true, bool start=false, bool end=false, bool low_power=false)
	Initialize an IoFrame header (ctrl0/ctrl1) with flags.
void	esphome::home_io_control::set_dst (IoFrame &f, const uint8_t id[NODE_ID_SIZE])
	Set destination node ID.
void	esphome::home_io_control::set_src (IoFrame &f, const uint8_t id[NODE_ID_SIZE])
	Set source node ID.
bool	esphome::home_io_control::set_cmd (IoFrame &f, uint8_t cmd, const uint8_t *params=nullptr, uint8_t params_len=0)
	Set command and payload.
uint8_t	esphome::home_io_control::frame_length (const IoFrame &f)
	Get total frame length from ctrl0.
bool	esphome::home_io_control::is_start (const IoFrame &f)
	Check START flag.
bool	esphome::home_io_control::is_end (const IoFrame &f)
	Check END flag.
uint8_t	esphome::home_io_control::serialize (const IoFrame &f, uint8_t *buf, uint8_t buf_size)
	Serialize a parsed frame into a wire buffer (without CRC).
bool	esphome::home_io_control::parse (const uint8_t *buf, uint8_t buf_len, IoFrame &f)
	Parse a wire buffer into a parsed IoFrame (validates length and CTRL0).
bool	esphome::home_io_control::hex_to_bytes (const std::string &hex, uint8_t *out, uint8_t len)
	Convert a hex string (e.g., "123ABC") to a byte array.
std::string	esphome::home_io_control::node_id_to_string (const uint8_t id[NODE_ID_SIZE])
	Format a 3‑byte node ID as a 6‑character uppercase hex string.
uint16_t	esphome::home_io_control::crc_ccitt (const uint8_t *data, uint8_t len)
	CRC-CCITT used by the IO-Homecontrol protocol for frame validation.

Variables
static constexpr uint8_t	esphome::home_io_control::CTRL0_END = 0x80
	Control byte 0 (CTRL0) bit definitions.
static constexpr uint8_t	esphome::home_io_control::CTRL0_START = 0x40
	Bit 6: first frame in exchange (uses long preamble).
static constexpr uint8_t	esphome::home_io_control::CTRL0_PROTOCOL_1W = 0x20
	Bit 5: 1=OneWay protocol, 0=TwoWay protocol.
static constexpr uint8_t	esphome::home_io_control::CTRL0_LENGTH_MASK = 0x1F
	Bits [4:0]: frame length - 1.
static constexpr uint8_t	esphome::home_io_control::CTRL1_VERSION_MASK = 0x03
	Control byte 1 (CTRL1) bit definitions.
static constexpr uint8_t	esphome::home_io_control::CTRL1_PRIORITY = 0x04
	Bit 2: high-priority frame.
static constexpr uint8_t	esphome::home_io_control::CTRL1_ACK = 0x10
	Bit 4: sender can handle 2W responses (ACK-capable).
static constexpr uint8_t	esphome::home_io_control::CTRL1_LOW_POWER = 0x20
	Bit 5: low-power device (e.g., solar-powered).
static constexpr uint8_t	esphome::home_io_control::CTRL1_ROUTED = 0x40
	Bit 6: frame was relayed through a repeater.
static constexpr uint8_t	esphome::home_io_control::CTRL1_BEACON = 0x80
	Bit 7: beacon announcement frame.

Detailed Description

IO-Homecontrol 2W frame container: control bytes, IoFrame and (de)serialization.

IO-Homecontrol is a proprietary wireless protocol used by Somfy, Velux, and other manufacturers for controlling shutters, awnings, blinds, and similar devices. "2W" means two-way: the controller sends commands and receives status feedback.

The protocol uses FSK modulation at 868 MHz with frequency hopping across 3 channels. Communication is encrypted with AES-128 and authenticated with a 6-byte HMAC. Each installation has a unique 16-byte "system key" shared between controller and devices.

This header owns only the frame container itself. The rest of the protocol model lives in cohesive headers (proto_sizes/proto_timing/proto_constants/proto_device_model/proto_codecs). New code should include the specific header it needs.

Definition in file proto_frame.h.