Sber Smart Home ⟷ Home Assistant MQTT Bridge

English documentation | Документация (GitHub Pages)

«Салют, включи свет на кухне» — и ваш Zigbee-выключатель, подключённый к Home Assistant, послушно выполняет команду.

Если вы собирали умный дом на Home Assistant, вы знаете это чувство: всё работает, автоматизации летают, дашборд выглядит идеально — но стоит кому-то из домашних попросить Салют выключить свет, и выясняется, что два мира ничего друг о друге не знают.

Sber Smart Home MQTT Bridge решает ровно эту проблему. Это нативная интеграция Home Assistant, которая делает ваши устройства HA видимыми для экосистемы Сбер — голосовых ассистентов Салют, приложения Сбер Умный дом — без отдельных серверов, аддонов или костылей. Один компонент, одна настройка через UI, и два мира начинают работать как один.

Идея простая: взять лучшее от каждой экосистемы. Home Assistant — это тысячи интеграций, гибкие автоматизации и сильное сообщество. Сбер — это голосовые ассистенты, удобное мобильное приложение и растущая линейка умных устройств. Этот мост позволяет использовать оба мира одновременно, не выбирая между ними.

Интеграция устанавливает MQTT-соединение с облаком Sber, транслирует ваши HA-устройства в формат Сбер Умного дома и мгновенно синхронизирует состояния в обе стороны. Команды от Салют превращаются в вызовы HA-сервисов, а изменения в HA моментально отражаются в приложении Сбер.

flowchart LR
    HA["🏠 Home Assistant\n(ваши устройства)"]
    Bridge["🔌 Sber MQTT Bridge\n(эта интеграция)"]
    Cloud["☁️ Облако Sber\n(MQTT broker)"]
    App["🗣️ Салют / Приложение Сбер\n(голос и мобильное управление)"]

    HA <--> Bridge <--> Cloud <--> App

Мост ничего не опрашивает — все обновления приходят push-сообщениями:

• Home Assistant → Сбер. Мост подписан на изменения состояний экспортируемых сущностей и отправляет новое состояние в Сбер сразу, объединяя изменения в пределах короткого окна (debounce_delay, по умолчанию 0,1 с). После команды из Сбера состояние отправляется ещё раз через confirm_delay (1,5 с), чтобы в приложение попали атрибуты, которые HA обновляет с задержкой.
• Сбер → Home Assistant. Команды и запросы состояния приходят из облака Сбера по MQTT и сразу превращаются в вызовы служб Home Assistant или ответы.
• Список устройств отправляется в Сбер при подключении, при изменении набора или настроек устройств и по запросу облака — с ожиданием загрузки устройств (см. «Тайминги синхронизации устройств»).
• Диагностические сущности моста обновляются по уведомлениям самого моста: частые изменения объединяются (не больше одной записи в 5 секунд на сущность), а смена фазы подключения и потеря связи показываются сразу.
• Связь с брокером держится постоянно; после обрыва мост переподключается с растущей паузой от 5 секунд до 5 минут (reconnect_interval_min / reconnect_interval_max).

• Нативная интеграция HA -- устанавливается через HACS, без дополнительных аддонов
• Настройка через UI -- полностью из интерфейса Home Assistant
• Массовый выбор устройств -- добавить все, по категориям, по меткам (labels), или поштучно
• Переопределение типов устройств -- смена категории Sber для каждого entity через UI или YAML
• Связывание entity (Entity Linking) -- привязка датчиков батареи, влажности, температуры к основному устройству: одно физическое устройство = одно устройство в Сбер
• Автоопределение связанных entity по общему device_id в мастере добавления
• Умная дедупликация -- если устройство имеет и light и switch, выбирается более функциональный вариант
• Синхронизация в реальном времени -- изменения в HA мгновенно видны в Сбер (debounce 100мс)
• Голосовое управление через всех ассистентов Сбер (Салют, Афина, Джой)
• 28 категорий Sber (27 типов устройств + hub) с автоматическим маппингом
• YAML-кастомизация -- sber_type, sber_name, sber_room, sber_nicknames, sber_groups, sber_features и другое
• Фильтрация по меткам (labels) -- экспорт entity по меткам HA
• Интеграция с HA Repairs -- автоматическое обнаружение проблем (отсутствующие entity, проблемы подключения)
• Сохранение переопределений -- переименования и комнаты из приложения Сбер переживают перезапуск HA
• Автоматическая повторная публикация конфигурации, когда Sber запрашивает неизвестные entity
• Валидация протокола через Pydantic -- строгая типизация JSON-сообщений Sber
• Автоматическое обнаружение дрейфа спецификации Sber -- еженедельный CI-scraper тянет каноничные схемы с developers.sber.ru, сравнивает с нашими моделями и открывает PR при расхождениях (см. tools/fetch_sber_schemas.py, tools/codegen.py)
• Runtime-валидация типов features -- сгенерированный из документации Sber словарь FEATURE_TYPES ловит несоответствия (напр. PIR как BOOL вместо ENUM) до отправки в облако
• Валидация обязательных features (✔︎ markers) -- CATEGORY_OBLIGATORY_FEATURES автоматически собирается из таблицы "Доступные функции устройства" Sber и гарантирует, что устройство эмитит полный набор обязательных функций (напр. valve без open_percentage ловится до публикации)
• Мониторинг подключения и диагностика
• Отслеживание подтверждения устройств -- видно, какие устройства Sber подтвердил
• Автоматическое переподключение с экспоненциальной задержкой (5сек -> 5мин)
• SSL сертификат (настраивается)
• Переводы: английский и русский
• CI/CD: ruff, pytest, HACS validation, hassfest, Sber spec drift detection
• 1760+ тестов

Модуль sber_constants.py содержит строго типизированные StrEnum-константы для всего протокола Sber:

• SberFeature — 74 ключа признаков устройств (все feature-имена протокола)
• SberValueType — типы значений (BOOL, INTEGER, ENUM, COLOUR, FLOAT)
• HAState — состояния Home Assistant (on, off, open, closed и др.)
• MqttTopicSuffix — суффиксы MQTT-топиков

Функции-фабрики для формирования значений протокола Sber:

• make_state() — создание структуры состояния
• make_bool_value() — булево значение
• make_integer_value() — целочисленное значение (возвращает строку согласно спецификации Sber)
• make_enum_value() — enum-значение
• make_colour_value() — цветовое значение HSV

Команды от Sber передаются в Home Assistant с заполненным Context, что обеспечивает корректную атрибуцию в журнале (logbook). В логах HA видно, что команда пришла именно от Sber-интеграции.

Метод has_significant_change() сравнивает новое состояние со старым перед каждой публикацией. Это исключает лишние MQTT publish при незначительных изменениях (например, при поллинге HA без реального изменения значения).

Логика онлайн-статуса дифференцирована по типу сенсора:

• Event-based binary_sensors (движение, дверь, протечка): unknown = online (датчик ждёт события)
• Value-based сенсоры (температура, влажность): unknown = offline (нет данных = нет связи)
• Значок "Loading..." в панели означает, что HA ещё не получил ни одного состояния от entity

Перед установкой интеграции нужно получить MQTT-учётные данные от Sber.

1. Перейдите на Sber Studio
2. Войдите с вашим Sber ID (тот же аккаунт, что и в приложении Сбер Умный дом)
3. Создайте рабочее пространство, если его ещё нет

1. В Sber Studio перейдите в раздел Умный дом
2. Нажмите Создать проект
3. Выберите тип MQTT-интеграция
4. Дайте проекту имя (например, "Home Assistant Bridge")

1. Откройте настройки проекта
2. Найдите раздел MQTT-подключение
3. Скопируйте Логин и Пароль -- они понадобятся в HA
4. Адрес брокера: mqtt-partners.iot.sberdevices.ru, порт: 8883

Подробная инструкция: Документация Sber MQTT-to-Cloud

1. Откройте приложение Сбер Умный дом или Салют на телефоне
2. Перейдите в Профиль > Дом от интегратора > Ввести пароль из шага 3
3. Ваша MQTT-интеграция должна появиться -- включите её
4. Устройства появятся в приложении после подключения моста

Нажмите кнопку выше — HACS откроется на странице репозитория, останется только нажать Download.

Или вручную:

1. Откройте HACS в Home Assistant
2. Нажмите меню (три точки) > Пользовательские репозитории
3. Добавьте https://github.com/dzerik/sber-mqtt-bridge с категорией Интеграция
4. Найдите "Sber Smart Home MQTT Bridge" и нажмите Установить
5. Перезагрузите Home Assistant

1. Скачайте последний релиз
2. Скопируйте папку custom_components/sber_mqtt_bridge/ в config/custom_components/ вашего HA
3. Перезагрузите Home Assistant

1. Перейдите в Настройки > Устройства и службы > Добавить интеграцию
2. Найдите "Sber Smart Home MQTT Bridge"
3. Введите учётные данные MQTT:

Основное управление устройствами — в панели Sber Bridge в боковом меню. Окно параметров интеграции — запасной путь без панели: Настройки > Устройства и службы > Sber Smart Home MQTT Bridge > Настроить.

На первом экране поле «Что вы хотите сделать?»:

Умная дедупликация (только в режимах «по доменам» и «ВСЕ»): если устройство HA регистрирует несколько сущностей, например light.кухня и switch.кухня, добавляется одна — с наивысшим приоритетом домена: light > cover > climate > water_heater > humidifier > vacuum > media_player > fan > valve > lock > switch > script > button, input_boolean, event > binary_sensor > sensor. Сущности без устройства HA добавляются всегда.

Для каждой экспортируемой сущности — выпадающий список категорий Sber. Auto (по умолчанию) — категория определяется по домену и device_class. Меняйте, если автоматика ошиблась: например, switch с лампой → light, или реле → socket, чтобы в приложении была иконка розетки. Если ни одна сущность ещё не выбрана, раздел сообщает об этом и закрывается.

Сбер считает каждую публикацию конфигурации полным списком устройств: устройство, которого в ней нет, облако удаляет, а когда оно появляется снова — заводит заново в комнате хаба. Поэтому при запуске и после изменений мост ждёт, пока устройства получат состояние.

Ожидание держат только устройства, которые Сбер уже знает: новое устройство, ещё не загрузившееся, просто появится в одной из следующих публикаций. Оба параметра дублируются на вкладке Настройки панели и применяются без перезапуска интеграции.

Панель Sber Bridge > вкладка Настройки. Значения сохраняются кнопкой Сохранить и применяются к работающему мосту без перезапуска интеграции; Reset to Defaults подставляет значения по умолчанию (их тоже нужно сохранить). Значение вне диапазона отклоняется целиком — ни один параметр из запроса не сохраняется.

Открываются кликом по устройству в таблице панели. Сохраняются для конкретной сущности и применяются без перезапуска интеграции.

Импульсные ворота (категория gate, реле switch / button / script со связанным датчиком положения):

Чайник (категория kettle, water_heater с режимами работы):

Меняйте режимы, если автоопределение не нашло нужный (панель показывает, какой режим сейчас используется). Если режим не найден или чайник не сообщает режимов, мост просто включает и выключает его.

Датчик температуры (категория sensor_temp): параметр temp_unit_view (по умолчанию true) решает, публиковать ли функцию temp_unit_view — шкалу отображения температуры. Отдельного поля в панели нет: нажмите Экспорт на панели инструментов, в файле задайте "gate_options": {"sensor.<имя>": {"temp_unit_view": false}} (блок gate_options хранит настройки всех устройств, не только ворот) и загрузите файл через Импорт. Выключайте, только если нужен минимальный набор функций: изменение набора функций заставляет Сбер зарегистрировать устройство заново, и оно теряет комнату.

Вы можете точно настроить отображение entity в Sber через configuration.yaml:

sber_mqtt_bridge:
  entity_config:
    light.kitchen:
      sber_type: light           # Переопределить категорию Sber
      sber_name: "Свет на кухне" # Имя в приложении Сбер
      sber_room: "Кухня"         # Назначение комнаты
      sber_nicknames:            # Альтернативные имена для голосового управления
        - "основной свет"
        - "потолочный свет"
      sber_groups:               # Группы устройств
        - "kitchen_lights"
      sber_features_add:         # Добавить возможности Sber
        - "colour_setting"
      sber_features_remove:      # Убрать возможности Sber
        - "colour_temp"
      sber_partner_meta: {}      # Пользовательские метаданные партнёра
      sber_parent_id: "light.living_room"  # ID родительского устройства

Связывание entity позволяет привязать вспомогательные HA-сущности (датчик батареи, уровень сигнала, влажность, температура) к основному устройству Sber. Это отражает физическую реальность: один Zigbee-датчик создаёт несколько entity в HA, но должен выглядеть как одно устройство в приложении Сбер.

Без связывания: датчик протечки с датчиком батареи создаёт два отдельных устройства Sber. Со связыванием: уровень заряда батареи автоматически включается в состояние датчика протечки — одно устройство, полные данные.

1. Выберите тип устройства и основную entity.
2. Мастер автоматически определяет связанные entity, разделяющие один device_id в HA.
3. Совместимые entity предвыбраны (отображаются зелёными). Несовместимые отображаются серым с пометкой "(not supported)".
4. Укажите имя и подтвердите.
5. Привязанные entity исчезают из списка доступных entity — ими управляет основное устройство.

Данные привязанных entity (уровень батареи, уровень сигнала и т.д.) включаются в каждую публикацию состояния основного устройства в Sber. Изменение состояния привязанной entity вызывает немедленную повторную публикацию состояния основного устройства.

Интеграция добавляет собственную панель в боковое меню Home Assistant (SPA-приложение):

Entity Preview в мастере добавления: при выборе типа устройства мастер показывает предварительный просмотр того, как entity будет выглядеть в Sber — какие features будут опубликованы.

Интеграция создаёт служебное устройство Sber MQTT Bridge с диагностическими сущностями — по ним удобно строить автоматизации на потерю связи. Пока мост остановлен, сущности недоступны.

После добавления устройств:

1. Откройте приложение Сбер Умный дом
2. Устройства появятся автоматически (может занять 10-30 секунд)
3. Переименовать устройство: нажмите на устройство > иконка настроек > измените имя
4. Назначить комнату: нажмите на устройство > иконка настроек > выберите комнату
5. Голосовое управление: скажите "Салют, включи свет на кухне"

Примеры голосовых команд:

• "Салют, включи свет в гостиной"
• "Салют, выключи все розетки"
• "Салют, какая температура в спальне?"
• "Салют, закрой шторы"
• "Салют, установи температуру 23 градуса"
• "Салют, включи увлажнитель"

Примечание: Переименования и назначения комнат, сделанные в приложении Сбер, сохраняются локально в интеграции и будут включены в будущие публикации конфигурации. Эти данные сохраняются при перезапуске HA.

• Нужен интернет. Мост работает только через облачный MQTT-брокер Сбера; локального управления без облака нет.
• Одна запись интеграции на Home Assistant. Если записей несколько (например, остались от старой версии), работает только одна, остальные не запускаются и показывают ошибку настройки — удалите лишние.
• Сбер считает каждую публикацию полным списком устройств. Устройство, выпавшее из публикации, облако удаляет и при следующем появлении заводит заново в комнате хаба. Мост ждёт загрузки устройств, но устройство, так и не получившее состояние за config_max_wait, в публикацию не попадёт.
• Только поддерживаемые категории. Экспортируются домены и возможности, для которых у Сбера есть категория и функции (см. «Поддерживаемые типы устройств»); остальные атрибуты устройств в приложении не видны.
• Переходные состояния блокируют кнопку в приложении. Пока ворота сообщают «открываются» / «закрываются», приложение Сбера не даёт управлять ими.
• Проверка на молчаливое отклонение неточна: Сбер может часами не запрашивать состояние принятого устройства, поэтому уведомление об этом по умолчанию выключено.
• Панель доступна только администраторам Home Assistant.

Вкладка DevTools в Sidebar Panel предоставляет инструменты для отладки без перезапуска HA:

• Raw Config — полная конфигурация устройств в формате JSON, который отправляется в Sber
• Raw States — текущие состояния всех устройств в Sber-формате
• MQTT Log — лог MQTT-сообщений в реальном времени (входящие и исходящие)

Интеграция использует систему Repairs в Home Assistant для уведомления о проблемах. Перейдите в Настройки > Ремонт для просмотра активных проблем:

• Отсутствующие entity, которые были ранее экспортированы
• Ошибки подключения MQTT
• Проблемы конфигурации

Добавьте в configuration.yaml:

logger:
  logs:
    custom_components.sber_mqtt_bridge: debug

Увидите:

• MQTT <- topic (N bytes) -- каждое входящее MQTT сообщение
• Sber -> HA command: entity_id [ключи] -- детали команды
• HA -> Sber state: entity_id = состояние -- публикация состояний
• Entity xxx -> Sber категория (домен, device_class) -- решения маппинга
• Sber error (#N): {...} -- ошибки от облака Sber

Перейдите в Настройки > Устройства и службы > Sber Smart Home MQTT Bridge > три точки > Скачать диагностику. Файл содержит:

• Статус подключения и время работы
• Счётчики сообщений (получено, отправлено, ошибки)
• Список подтверждённых/неподтверждённых устройств
• Конфигурацию устройств

При удалении записи мост просто отключается от брокера и ничего не отправляет в Сбер, поэтому устройства остаются в приложении Сбер Умный дом: они больше не обновляются и не выполняют команды. Чтобы они исчезли автоматически, очистите список до удаления, пока мост подключён:

1. Удалите устройства в таблице панели Sber Bridge или откройте Настроить > Advanced entity management (fallback) > Выбор сущностей > Remove ALL entities.
2. Мост отправит в Сбер конфигурацию без устройств, и облако удалит их из приложения.
3. Убедитесь, что устройства пропали из приложения, и переходите к следующему шагу.

Если запись уже удалена, удалите оставшиеся устройства вручную в приложении Сбер Умный дом. Если MQTT-проект больше не нужен, отключите интеграцию в приложении там же, где её подключали (Настройки > Подключенные сервисы), и удалите проект в Sber Studio — выданные для него логин и пароль перестанут действовать.

1. Настройки > Устройства и службы > Sber Smart Home MQTT Bridge.
2. Меню записи (три точки) > Удалить.

Вместе с записью удаляются: панель Sber Bridge из бокового меню, служебное устройство «Sber MQTT Bridge» с его диагностическими сущностями, уведомления интеграции в Ремонте и все настройки, хранящиеся в записи: список экспортируемых сущностей, переопределения типов, связи сущностей, настройки отдельных устройств, имена и комнаты из приложения Сбер, параметры моста. Сами сущности Home Assistant, которые вы экспортировали, не затрагиваются.

Секцию sber_mqtt_bridge: в configuration.yaml (если вы её добавляли) и строку custom_components.sber_mqtt_bridge в настройках logger: удалите вручную.

• HACS: HACS > найдите Sber Smart Home MQTT Bridge > меню (три точки) > Удалить.
• Ручная установка: удалите папку config/custom_components/sber_mqtt_bridge/.

После этого перезагрузите Home Assistant.

Все названия продуктов, логотипы и бренды, упомянутые в этом проекте, являются собственностью их владельцев:

• Сбер, SberDevices, Салют, Сбер Умный дом -- торговые марки Сбер (ПАО Сбербанк).
• Home Assistant -- торговая марка проекта Home Assistant.
• HACS (Home Assistant Community Store) -- независимый проект сообщества.

Этот проект не связан, не одобрен и не спонсирован Сбером, SberDevices или проектом Home Assistant. Это независимая интеграция с открытым исходным кодом.

• Документация проекта (GitHub Pages)
• API Reference
• Портал разработчиков Sber Smart Home
• Регистрация в Sber Studio
• Руководство MQTT-to-Cloud
• Поддерживаемые категории устройств

Смотрите CONTRIBUTING.md для настройки среды разработки и рекомендаций.

MIT

Чат в Telegram: @ha_sber_chat — общий чат по интеграциям ha-sberhome, ha-sboom-card, holabrain-ha и sber-mqtt-bridge. Вопросы по установке и настройке, обсуждение новых устройств, ранние сборки. Баг-репорты лучше заводить issue'ами в соответствующем репозитории.