Модели протокола

Pydantic-модели для валидации и конструирования JSON-структур протокола Sber Smart Home.

Pydantic models for Sber Smart Home MQTT protocol.

Provides typed schemas for Sber protocol payloads (device config, states, commands) and helper functions for constructing protocol values.

These models serve as: - Reference documentation for the Sber JSON protocol - Optional validation layer for outgoing MQTT payloads - Type-safe constructors for Sber state values

SberValue

Bases: BaseModel

A typed value in Sber state or command payload.

Sber protocol uses tagged unions: the type field selects which *_value field carries the actual data.

Attributes:

Name	Type	Description
type	Literal['BOOL', 'INTEGER', 'FLOAT', 'STRING', 'ENUM', 'COLOUR']	Value type discriminator.
bool_value	bool | None	Boolean payload (for BOOL type).
integer_value	str | None	Integer payload as string (for INTEGER type).
float_value	float | None	Float payload (for FLOAT type).
string_value	str | None	String payload (for STRING type).
enum_value	str | None	Enum string payload (for ENUM type).
colour_value	dict[str, int] | None	HSV colour dict (for COLOUR type).

SberState

Bases: BaseModel

Single state key-value pair in the Sber protocol.

Attributes:

Name	Type	Description
key	str	State key name (e.g. "online", "on_off", "brightness").
value	SberValue	Typed value for the key.

SberDeviceModel

Bases: BaseModel

Device model descriptor within a Sber device config.

Attributes:

Name	Type	Description
id	str	Model identifier string.
manufacturer	str	Device manufacturer name.
model	str	Device model name.
description	str	Human-readable description.
category	str	Sber device category (e.g. "light", "relay").
features	list[str]	List of supported feature keys.
allowed_values	dict[str, Any]	Optional dict of feature constraints.

SberDevice

Bases: BaseModel

Full device descriptor for Sber config publish.

Per Sber spec (VR-001), model_id and model are mutually exclusive. This integration always uses inline model; model_id is not emitted.

Attributes:

Name	Type	Description
id	str	Device / entity identifier.
name	str	Display name.
default_name	str | None	Fallback name (usually entity_id).
room	str	Room / area identifier.
home	str | None	Home / location name (e.g. "Мой дом").
model	SberDeviceModel	Nested device model descriptor (mutually exclusive with model_id).
hw_version	str	Hardware version string.
sw_version	str	Software version string.
nicknames	list[str] | None	Alternative voice names.
groups	list[str] | None	Device groups.
parent_id	str | None	Parent device entity_id for hub hierarchy.
partner_meta	dict[str, str] | None	Arbitrary key-value metadata for partner integrations.

SberDeviceState

Bases: BaseModel

Current state of a single device.

Attributes:

Name	Type	Description
states	list[SberState]	List of state key-value pairs.

SberConfigPayload

Bases: BaseModel

Config publish payload (device list).

Attributes:

Name	Type	Description
devices	list[SberDevice | dict[str, Any]]	List of device descriptors (SberDevice or raw dict).

SberStatusPayload

Bases: BaseModel

Status publish payload (device states).

Attributes:

Name	Type	Description
devices	dict[str, SberDeviceState]	Mapping of device_id to its current state.

SberCommandPayload

Bases: BaseModel

Incoming command payload from Sber cloud.

Attributes:

Name	Type	Description
devices	dict[str, SberDeviceState]	Mapping of device_id to command states.

make_bool_value

make_bool_value(value)

Create a Sber BOOL value dict.

Parameters:

Name	Type	Description	Default
value	bool	Boolean value.	required

Returns:

Type	Description
dict[str, Any]	Dict ready for inclusion in a Sber state payload.

Source code in custom_components/sber_mqtt_bridge/sber_models.py

def make_bool_value(value: bool) -> dict[str, Any]:
    """Create a Sber BOOL value dict.

    Args:
        value: Boolean value.

    Returns:
        Dict ready for inclusion in a Sber state payload.
    """
    return {"type": "BOOL", "bool_value": value}

make_integer_value

make_integer_value(value)

Create a Sber INTEGER value dict.

Per Sber C2C specification, integer_value is serialized as a string.

Parameters:

Name	Type	Description	Default
value	int	Integer value.	required

Returns:

Type	Description
dict[str, Any]	Dict ready for inclusion in a Sber state payload.

Source code in custom_components/sber_mqtt_bridge/sber_models.py

def make_integer_value(value: int) -> dict[str, Any]:
    """Create a Sber INTEGER value dict.

    Per Sber C2C specification, ``integer_value`` is serialized as a string.

    Args:
        value: Integer value.

    Returns:
        Dict ready for inclusion in a Sber state payload.
    """
    return {"type": "INTEGER", "integer_value": str(value)}

make_enum_value

make_enum_value(value)

Create a Sber ENUM value dict.

Parameters:

Name	Type	Description	Default
value	str	Enum string value.	required

Returns:

Type	Description
dict[str, Any]	Dict ready for inclusion in a Sber state payload.

Source code in custom_components/sber_mqtt_bridge/sber_models.py

def make_enum_value(value: str) -> dict[str, Any]:
    """Create a Sber ENUM value dict.

    Args:
        value: Enum string value.

    Returns:
        Dict ready for inclusion in a Sber state payload.
    """
    return {"type": "ENUM", "enum_value": value}

make_colour_value

make_colour_value(h, s, v)

Create a Sber COLOUR value dict.

Parameters:

Name	Type	Description	Default
h	int	Hue component (0-360).	required
s	int	Saturation component (0-100).	required
v	int	Value/brightness component (0-100).	required

Returns:

Type	Description
dict[str, Any]	Dict ready for inclusion in a Sber state payload.

Source code in custom_components/sber_mqtt_bridge/sber_models.py

def make_colour_value(h: int, s: int, v: int) -> dict[str, Any]:
    """Create a Sber COLOUR value dict.

    Args:
        h: Hue component (0-360).
        s: Saturation component (0-100).
        v: Value/brightness component (0-100).

    Returns:
        Dict ready for inclusion in a Sber state payload.
    """
    return {"type": "COLOUR", "colour_value": {"h": h, "s": s, "v": v}}

make_state

make_state(key, value)

Create a Sber state entry dict.

Parameters:

Name	Type	Description	Default
key	str	State key name.	required
value	dict[str, Any]	Typed value dict (from make_*_value helpers).	required

Returns:

Type	Description
dict[str, Any]	Dict with key and value keys.

Source code in custom_components/sber_mqtt_bridge/sber_models.py

def make_state(key: str, value: dict[str, Any]) -> dict[str, Any]:
    """Create a Sber state entry dict.

    Args:
        key: State key name.
        value: Typed value dict (from ``make_*_value`` helpers).

    Returns:
        Dict with ``key`` and ``value`` keys.
    """
    return {"key": key, "value": value}

validate_config_payload

validate_config_payload(data)

Validate a config payload dict against the SberConfigPayload schema.

This is an optional validation step — failures are logged as warnings but do not prevent publishing (the raw dict is still valid JSON).

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Raw dict to validate.	required

Returns:

Type	Description
bool	True if validation passed, False otherwise.

Source code in custom_components/sber_mqtt_bridge/sber_models.py

def validate_config_payload(data: dict[str, Any]) -> bool:
    """Validate a config payload dict against the SberConfigPayload schema.

    This is an optional validation step — failures are logged as warnings
    but do not prevent publishing (the raw dict is still valid JSON).

    Args:
        data: Raw dict to validate.

    Returns:
        True if validation passed, False otherwise.
    """
    try:
        SberConfigPayload.model_validate(data)
    except (ValueError, TypeError):
        _LOGGER.warning("Config payload validation failed", exc_info=True)
        return False
    return True

validate_status_payload

validate_status_payload(data)

Validate a status payload dict against the SberStatusPayload schema.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Raw dict to validate.	required

Returns:

Type	Description
bool	True if validation passed, False otherwise.

Source code in custom_components/sber_mqtt_bridge/sber_models.py

def validate_status_payload(data: dict[str, Any]) -> bool:
    """Validate a status payload dict against the SberStatusPayload schema.

    Args:
        data: Raw dict to validate.

    Returns:
        True if validation passed, False otherwise.
    """
    try:
        SberStatusPayload.model_validate(data)
    except (ValueError, TypeError):
        _LOGGER.warning("Status payload validation failed", exc_info=True)
        return False
    return True