Нативная интеграция Sber Smart Home (приложение «Салют!») в Home Assistant.
Привозит устройства из экосистемы Сбер (свет, розетки, датчики, климат, шторы,
пылесосы, ТВ, домофоны, чайники) в HA через официальный Sber Gateway API
(gateway.iot.sberdevices.ru) с OAuth2/PKCE авторизацией через id.sber.ru
и WebSocket push для мгновенных обновлений.
Отдельная благодарность проекту altfoxie/ha-sberdevices — его находки по авторизации стали отправной точкой для ha-sberhome. Мы вдохновились и переработали всё под своё видение, но стоим у него на плечах.
В v5.1.0 добавлен второй путь авторизации — через SMS-OTP (beta).
Механизм и алгоритм CSAFront-flow (/authenticate → /verify →
/oidc/v3/token → /v13/smarthome/token) взят полностью из
открытого источника — проекта
shuryak/sberdevices (Go,
MIT-license). Все endpoint'ы, заголовки, anti-bot rsa_data ритуал,
persistent X-Device-ID, шаги refresh-rotation — переиспользованы
оттуда без изменений по существу; портировано на Python/asyncio и
интегрировано в общий aiosber-стек. Огромная благодарность автору
открытой реализации — без неё бета-путь не появился бы.
Note
Если вам, наоборот, нужно выставить HA-устройства в Салют (голосовое управление «Салют, включи свет»), посмотрите sister-проект sber-mqtt-bridge — выставление HA → Сбер через MQTT-партнёрский API.
Этот проект:
- не аффилирован с ПАО Сбербанк, SberDevices, экосистемой «Салют» или любыми их дочерними структурами;
- работает только с устройствами, принадлежащими конечному
пользователю, и только под его собственной учётной записью
Sber Smart Home — авторизация всегда происходит от имени пользователя
его собственными credentials (Sber ID OAuth через
id.sber.ruлибо SMS-OTP на привязанный к аккаунту телефон); - использует публично задокументированный Sber ID OAuth-flow
(
id.sber.ru/CSAFront/oidc/authorize.do+/oidc/v3/token) в качестве основного пути авторизации — тот же самый, что использует официальный Sber ID iOS SDK; - для бета-режима SMS-OTP wire-format взят из открытого MIT-проекта shuryak/sberdevices с явной атрибуцией; декомпиляция, дизассемблирование, обход технических средств защиты, перехват чужого трафика — не использовались;
- предоставляется AS-IS, без гарантий: Sber может в любой момент изменить или отозвать endpoint'ы, и интеграция перестанет работать до обновления;
- не имитирует виртуального ассистента «Салют» и не задействует его Voice/NLP-функции — реализует только функцию management собственных устройств пользователя, дополняющую штатное приложение, а не заменяющую его.
Полная правовая позиция — в LEGAL.md (ст. 1280 ГК РФ, EU Software Directive 2009/24/EC, анализ публичных документов Sber).
Если вы считаете, что проект нарушает чьи-то права — откройте issue или напишите автору, мы оперативно прислушаемся.
Товарные знаки Sber, SberDevices, Салют, SberHome, SberBoom принадлежат соответствующим правообладателям; их упоминание в документации — nominative use для обозначения совместимости.
flowchart LR
App["📱 Приложение\n«Салют!»"]
Cloud["☁️ Sber Cloud\n(Gateway API)"]
HA["🏠 Home Assistant\n(ваша установка)"]
User["👤 Пользователь\n(dashboard / automations)"]
App <-->|"REST + WS"| Cloud
Cloud <-->|"OAuth2 PKCE\nREST + WebSocket push"| HA
HA <-->|"native entities"| User
- OAuth2 PKCE через
id.sber.ru→ получение «companion» токена, которым ходит мобильное приложение «Салют!». - Polling
GET /device_groups/treeдля discovery устройств и комнат. - WebSocket push
wss://ws.iot.sberdevices.ruдля real-timeDEVICE_STATE(включение/выключение, изменение атрибутов датчиков) — polling снижается до 10 минут, пока WS жив. - HA ↔ Sber команды через
PUT /devices/{id}/state.
- 🎙️ Voice Intents UI — bidirectional bridge с Sber-сценариями.
Создавай / редактируй / удаляй / запускай Sber-scenarios прямо из HA
UI (вкладка «Voice Intents»). Schema-driven extensible форма, picker
всех Sber-устройств без HA-enabled фильтра. Sber-сценарии фразой
пробрасываются в HA как
sberhome_intentevent для автоматизаций. Подробности в секции «Что нового в 4.x». - 29 категорий устройств — полное покрытие Sber Gateway API (свет, розетки, реле, датчики темп/влажности/протечки/двери/движения/ дыма/газа, шторы, ворота, клапаны, все HVAC, увлажнители, очистители, чайники, пылесосы, ТВ, сценарные кнопки, домофоны, хабы, колонки SberBoom/Portal/Box/Satellite).
- Sber Cloud Scenarios → HA buttons — каждый твой Sber-сценарий
(
/scenario/v2/scenario) появляется какbuttonentity. Нажми в HA → выполняется в облаке Сбера. Идеально для интеграции в HA- автоматизации триггеров от датчиков HA, которых нет в Sber. - At-home presence —
binary_sensor.sber_at_homeзеркалит глобальную переменнуюat_homeиз Sber-облака; парныйswitch.sber_at_homeпишет обратно. Используй какconditionилиtriggerв HA-автоматизациях («когда пришёл домой»). - Sber LED indicator —
light.sber_indicator_color(HSV) управляет цветом и яркостью LED-кольца на колонках Сбера черезIndicatorAPI. - Per-device firmware updates —
update.<device>_firmwareper устройству показывает доступную версию прошивки из/inventory/ota-upgradesрядом с installed (sw_version). Когда Sber публикует обновление — золотой колокольчик в шапке HA. Установка управляется Sber-облаком (HA-side install не реализован). - Hub diagnostics — для SberBoom Home / SberPortal / intercom
координатор раз в час дёргает
/devices/{id}/discoveryи экспонируетsensor.<hub>_subdevice_count— сколько связанных через хаб устройств. - Opt-in picker — устройства не создаются в HA автоматически; вы выбираете нужные во встроенной панели. Неподдерживаемые категории визуально приглушаются с бейджем «не поддерживается» и не включаются (server-side guard).
- Real-time WebSocket push — изменение состояния датчика в Сбер → мгновенно в HA (обычно <2 сек).
- Adaptive polling — когда WS активен, REST-опрос раз в 10 минут (только для discovery новых устройств и ренеймов); при обрыве WS возвращается к пользовательскому интервалу (default 30 сек).
- Multi-cadence background polling — сценарии каждые 5 минут, OTA / discovery / indicator каждый час (отдельно от device tree, чтобы не нагружать API). Best-effort: ошибка в одном potoke не валит остальные.
- Опционные Zigbee-датчики — реле/лампочки подтягивают Zigbee-сенсоры производителя (батарея, сигнал, tamper, alarm_mute).
- Intercom-кнопки
button.intercom_unlock/button.intercom_reject_call— управление домофоном из HA. - Pairing WS surface — 8 WS-команд поверх
PairingAPI(Wi-Fi / Zigbee / Matter handshake) для будущего custom-panel «Add device» wizard. Полноценный config_flow UI пока не реализован, surface готов. - Встроенная панель DevTools (вкладка Monitor в сайдбаре):
- State Diffs — дельта
reported_stateвместо полного payload'а, чтобы увидеть что именно поменялось. - Command Confirmation Tracker — ловит silent rejection от Sber
(HTTP 200 без применения команды) по отсутствию ключей в
следующем
reported_state. - Schema Validation — детектит API drift на лету.
- Replay / Inject — подсунуть синтетический WS-пейлоад в coordinator для отладки без физического устройства.
- Per-device Diagnose — один клик → вердикт
ok/warning/broken+ actionable next step.
- State Diffs — дельта
- Raw command debug — сервис
sberhome.send_raw_commandдля отправки произвольногоAttributeValueDtoв обход маппинга. - Reauth Flow — автоматическое предложение повторной авторизации при истечении токена.
- Options Flow — настраиваемый интервал опроса API (10–300 секунд).
- Diagnostics — полный отчёт с редакцией токенов.
- Локализация — русский, английский, казахский, белорусский, узбекский.
- 1058 тестов — unit + HA-integration (pytest + pytest-homeassistant-custom-component + respx).
Освещение — умные лампы (light), светодиодные ленты
(led_strip, + sleep_timer).
Электрика — умные розетки (socket, + напряжение/ток/мощность +
child_lock), реле (relay, + измерения).
Датчики — температуры/влажности/давления (sensor_temp),
протечки воды (sensor_water_leak), открытия двери/окна
(sensor_door, + tamper, sensitivity), движения (sensor_pir),
дыма (sensor_smoke), утечки газа (sensor_gas). Все — с
батареей, сигналом и low-battery флагом.
Шторы / ворота — curtain, window_blind, gate, valve —
open/close/position/open_rate. Двустворчатые — отдельные _left /
_right сущности.
HVAC — кондиционеры (hvac_ac), обогреватели (hvac_heater),
радиаторы (hvac_radiator), бойлеры (hvac_boiler), тёплый пол
(hvac_underfloor_heating), вентиляторы (hvac_fan), очистители
воздуха (hvac_air_purifier), увлажнители (hvac_humidifier) —
полное покрытие features spec: current + target temp, humidity,
fan speeds, hvac modes, air flow direction, night/ionization/
aromatization, water level/low diagnostics.
Бытовая техника — чайники (kettle), роботы-пылесосы
(vacuum_cleaner), телевизоры (tv, source/volume/channel/mute +
custom_key/direction/channel IR-style services).
Другое — сценарные выключатели (scenario_button, события
click/double_click/long_press для до 10 кнопок и directional-вариантов
- виртуальные c2c-кнопки
cat_button_*типа «Эмуляция присутствия»), домофоны (intercom), хабы (hub), колонки/портал (sber_speaker— SberBoom Home/Mini, SberPortal, SberBox, SberSatellite). Через REST у Sber-владельных колонок media-control недоступен (это архитектурный лимит Gateway), но мы экспонируем connectivity + Zigbee/Matter readiness + position select + LED-индикатор.
Главная фича 4.x: двустороннее управление Sber-сценариями из HA + ловля голосовых команд через Sber-колонку как HA event'ы. Не нужно мобильное приложение «Салют!» для типичных сценариев — вся работа из вкладки «Voice Intents» в SberHome panel.
- Создавать / редактировать / удалять Sber-сценарии прямо из HA UI. Schema-driven форма: имя + список фраз (chips) + actions (TTS / device_command / push / HA-event-only).
- Запустить сценарий по кнопке (▶ Test) — реальный программный run
через
POST /scenario/v2/scenario/{id}/run(то же что кнопка «Запустить действие» в Sber-приложении). Колонка озвучит TTS, выполнит device-команду, и т.п. - Ловить срабатывания через
sberhome_intentHA event — для любого Sber-сценария (включая созданные руками в мобилке). Без виртуальных кнопок-посредников: подписан наscenario_widgetsWS-топик, получает push при каждом срабатывании, дёргает/scenario/v2/eventдля metadata, fire'ит HA event. - Picker колонок не ограничен HA enabled-set. При выборе устройства для TTS-action виден весь Sber-side list (даже колонки не подключённые в HA через picker) — Sber выполнит сценарий в облаке, HA-import не нужен.
- Live
last_fired_at. В UI видно когда последний раз сценарий сработал, обновляется real-time через event-bus subscription. - Forward-compat для незнакомых Sber-actions (новые task types, RegimeCommand и т.п.) — UI помечает «sber-only» и сохраняет raw_extras при update без потерь.
HA → SberHome (sidebar) → вкладка Voice Intents
┌────────────────────────────────────────────────────────────┐
│ Воice Intents [+ Новый intent] │
├────────────────────────────────────────────────────────────┤
│ Утренний кофе 🔥 2 мин назад │
│ «утренний кофе», «сделай кофе» │
│ tts [▶ Test] [✎] [🗑] │
├────────────────────────────────────────────────────────────┤
│ Холодно ── Sber-only ── │
│ «Холодно» │
│ trigger_notify [▶ Test] [✎] [🗑] │
└────────────────────────────────────────────────────────────┘
# automations.yaml — сценарий «Маркер один» создан в Sber-приложении
# или через нашу UI-вкладку (с любыми actions: TTS, push, ничего)
automation:
- alias: HA reacts to Sber voice intent
trigger:
- platform: event
event_type: sberhome_intent
event_data:
name: "Маркер один"
action:
- service: notify.persistent_notification
data:
message: "Sber-сценарий «{{ trigger.event.data.name }}» сработал!"
title: Voice intent caughtPayload event'а: {name, scenario_id, event_time, type, account_id, simulated}.
simulated: true маркирует HA-side test-симуляции — реальные срабатывания
от голоса колонки имеют simulated: false (или поле отсутствует).
Latency end-to-end (произнесение фразы → trigger в HA): ~300-500 мс.
Нет прямого «say arbitrary text» REST-API в Sber Gateway, но есть работающий путь через named-сценарий:
- В UI вкладке Voice Intents создаёшь intent например «уведомление о температуре»: action = TTS «Включаю обогрев», device = SberBoom Home.
- В HA-автоматизации триггеришь Sber-сценарий через
sberhome.run_scenarioservice (запускает через REST). Колонка озвучит фразу.
automation:
- alias: Heater on when cold
trigger:
- platform: numeric_state
entity_id: sensor.living_room_temp
below: 18
action:
# Запустить Sber-сценарий «Включаю обогрев» (создан в UI)
- service: button.press
target:
entity_id: button.sber_scenarios_vklyucayu_obogrev
- service: switch.turn_on
target:
entity_id: switch.heater// Список intent'ов
await hass.callWS({ type: "sberhome/intents/list" });
// Schema для динамической UI-формы (action types + fields)
await hass.callWS({ type: "sberhome/intents/schema" });
// Picker устройств (без HA-enabled фильтра)
await hass.callWS({
type: "sberhome/intents/devices_for_picker",
category: "sber_speaker"
});
// Create / update / delete / get / test
await hass.callWS({
type: "sberhome/intents/create",
spec: {
name: "Утренний кофе",
phrases: ["утренний кофе", "сделай кофе"],
actions: [{ type: "tts", data: {
phrase: "Запускаю!", device_ids: ["d7l4..."]
}}]
}
});
await hass.callWS({
type: "sberhome/intents/test",
intent_id: "sc-1"
});Backend intents/registry.py использует ActionRegistry pattern — добавить
новый action_type = одна запись + 2 функции (encode/decode). UI получит
новую option автоматически через intents/schema. Добавить новый
field type в форме (например slider, color_picker) = ~20 строк JS
в _renderInputForType в sberhome-intent-modal.js.
Forward-compat: незнакомые поля Sber wire-формата сохраняются в
IntentSpec.raw_extras и мерджатся обратно при update. Sber может
добавить новое поле — наш код не упадёт. Пользователь создал в мобилке
сценарий с экзотическим action типом — UI пометит как «complex/read-only»,
raw сохраняется и не теряется.
Каждый сценарий из мобильного приложения «Салют!» появляется в HA как button под virtual-устройством «Sber Scenarios»:
# Пример automation: запустить Sber-сценарий «Уход из дома»,
# когда HA-датчик подтвердил отсутствие
automation:
- alias: Sber Goodbye on HA away
trigger:
- platform: state
entity_id: binary_sensor.someone_home
to: "off"
for: "00:05:00"
action:
- service: button.press
target:
entity_id: button.sber_scenarios_uhod_iz_doma# Пример: включаем свет в коридоре только если at_home == true
automation:
- alias: Hallway light when at home
trigger:
- platform: state
entity_id: binary_sensor.hallway_motion
to: "on"
condition:
- condition: state
entity_id: binary_sensor.sber_at_home
state: "on"
action:
- service: light.turn_on
target:
entity_id: light.hallway
# Зеркальный поток: устанавливаем at_home из HA
automation:
- alias: Set Sber at_home when arriving
trigger:
- platform: state
entity_id: device_tracker.my_phone
to: "home"
action:
- service: switch.turn_on
target:
entity_id: switch.sber_at_home# Пример: окрасить кольцо на колонке в красный когда сработал датчик дыма
automation:
- alias: Red ring on smoke alarm
trigger:
- platform: state
entity_id: binary_sensor.kitchen_smoke
to: "on"
action:
- service: light.turn_on
target:
entity_id: light.sber_indicator_color
data:
hs_color: [0, 100]
brightness: 255update.<device>_firmware per устройству выключен по умолчанию в
registry — слишком много шума, если включать всем 50 датчикам. Включи
вручную для тех устройств, прошивку которых хочешь tracked:
Settings → Devices & services → SberHome → нажми устройство → «+1 hidden entity» → toggle
Firmware.
Когда в Sber появляется обновление — HA отрисует золотой колокольчик в шапке. Сама установка — через мобильное приложение Сбер (server-side rollout, HA-side install не реализован).
Для SberBoom Home / SberPortal / intercom создаётся диагностический
sensor.<hub>_subdevice_count — сколько устройств связано через этот
хаб. Полезно для проверки «всё ли видит хаб после рестарта» (Zigbee
драйверы иногда забывают peer'ов).
Все API-домены aiosber доступны через coordinator.client:
// В custom panel или HACS-карте
const rooms = await hass.callWS({ type: "sberhome/get_rooms" });
await hass.callWS({
type: "sberhome/rename_room",
room_id: "g-1",
name: "Гостиная",
});
// Pairing flow surface (для будущего Add-device wizard)
const creds = await hass.callWS({
type: "sberhome/pairing/wifi_credentials",
});
await hass.callWS({
type: "sberhome/pairing/start",
pairing_type: "wifi",
image_set_type: "dt_bulb_e27_m",
timeout: 60,
});
// Manual refresh после временной сетевой ошибки
await hass.callWS({ type: "sberhome/refresh_scenarios" });
await hass.callWS({ type: "sberhome/refresh_ota" });Кликните бейдж в начале README, либо: HACS → ⋮ → Custom repositories →
URL: https://github.com/dzerik/ha-sberhome, Category: Integration.
Скопируйте custom_components/sberhome/ в custom_components/ вашей
конфигурации HA и перезапустите.
- Настройки → Devices & services → Add integration → найти SberHome.
- Откроется страница авторизации с инструкциями.
- Нажмите «Войти через Сбер ID» — в новой вкладке откроется страница входа.
- Авторизуйтесь через Сбер ID.
- После входа браузер покажет «ошибку» — это нормально; скопируйте URL консоли в DevTools (он начинается с
companionapp://). - Вернитесь на страницу авторизации, вставьте URL в поле и нажмите «Подтвердить».
- Готово — в панели SberHome в сайдбаре выбирайте устройства которые хотите завести в HA.
Если firmware лампы/ленты поддерживает динамические сцены, HA автоматически подключает effect-feature. Запуск из автоматизации:
- service: light.turn_on
target:
entity_id: light.lenta_zal
data:
effect: "Радуга"Полный список доступных эффектов виден в light.effect_list (Lovelace
отображает их в стандартной light-card dropdown'ом). Эффект включается
только если в attributes[].light_mode.enum_values устройства есть
значение scene — лампы без поддержки сцен EFFECT-feature не получают.
Если передать неизвестное имя эффекта — в лог уйдёт warning, лампа
включится обычным turn_on (без сцены).
Каждая user-created группа в приложении «Салют!» (например «Освещение
прихожей») появляется в HA как switch.<group_name>. Toggle
отправляет одну bulk-команду в Sber — Sber серверной стороной разъезжает
её по всем устройствам группы (быстрее и атомарнее, чем N отдельных
команд из HA). Пустые группы (без устройств) в HA не появляются.
Aggregated state:
is_on=True— если хоть одно устройство группы включено;is_on=False— если все on_off-устройства группы выключены;is_on=None(unknown) — если в группе вообще нет устройств с атрибутомon_off(например, группа из штор/датчиков).
available=False если все устройства группы offline.
🧪 EXPERIMENTAL. Каждый вызов = 2–3 API-call'а в облако Sber. Не для частых уведомлений (>1/мин). Sber может изменить wire-формат или начать лимитировать.
Для каждого дома Sber регистрируется HA-entity notify.sberhome_<home_slug>.
Вызов:
automation:
- alias: "Уведомление об ужине"
trigger:
platform: time
at: "19:00:00"
action:
- service: notify.send_message
target:
entity_id: notify.sberhome_moy_dom
data:
message: "Ужин готов"Под капотом: интеграция находит (или создаёт) один Sber-сценарий-болванку
per home с маркером в description, PUT'ит pronounce_data.phrase +
device_ids, POST /run. Sber произносит фразу через указанные колонки.
Открой панель SberHome → вкладка Automations → segment 🔊 TTS:
- Статус surrogate-сценариев per home (создан / не создан, кнопка «Создать сейчас»).
- Тестовая форма: дом, фраза, выбор колонок. Показывает реальный latency после вызова.
- Автогенерированный YAML-сниппет для копи-пасты в
configuration.yaml.
По умолчанию — все колонки указанного дома (тип sber_speaker через
image_set_type / full_categories[0].slug).
Override — через data.device_ids (raw Sber UUIDs, можно найти в
UI-табе или в device-table):
data:
message: "Только кухня"
device_ids:
- "<sber-device-uuid-kitchen-speaker>"HA target (media_player entity_id) пока не резолвится — будет
в будущей минорной версии. Используйте data.device_ids.
- 1 surrogate scenario per home создаётся при первом use.
- Concurrency: при одновременных вызовах на один home — race на edit'е, Sber произнесёт что-то.
- Latency: ~500ms–2s на вызов.
- API rate: 2–3 request per call. Не для high-freq.
Помимо intents: (создающих Sber-сценарии с голосовыми фразами)
можно объявить listeners — pure HA-side подписку на Sber-event'ы
с любым триггером (TIME / DEVICE / GEO_TIME / CONDITIONS / …):
sberhome:
listeners:
- slug: morning_time
name: "Утренние time-сценарии"
filter:
trigger_type: TIME
scenario_name: "Доброе утро"При срабатывании Sber-сценария «Доброе утро» (по time-триггеру), HA
получит event sberhome_intent с event_data.slug=morning_time —
HA-automation биндится по slug:
automation:
- alias: "Morning time scenario fired"
trigger:
platform: event
event_type: sberhome_intent
event_data:
slug: morning_time
action: ...Listeners — read-only. Они не создают и не изменяют Sber-сценарии. Sber-сценарий с TIME/DEVICE/GEO_TIME-триггером должен быть заранее создан в приложении «Салют!».
trigger_type— string или list. Допустимы:PHRASES,TIME,DEVICE,GEO_TIME,CONDITIONS,CHECK_DEVICE,CHECK_SCENARIO,UNDEFINED_TYPE.scenario_name— exact match (case/whitespace tolerant).scenario_id— Sber UUID, exact.home(имя) /home_id(UUID) — для multi-home setup'ов.
Минимум одно поле обязательно. AND между полями; OR внутри списка
trigger_type: [...].
- Listeners перечитываются только при полной перезагрузке HA
(
reload_intentsservice не затрагивает listeners). - Создание не-фразовых триггеров через Sber API не поддержано — wire-формат неизвестен. Listeners — только read-only маппинг.
Помимо UI-вкладки «Voice Intents», голосовые сценарии можно
описывать декларативно в configuration.yaml — удобно для
version-control'а и воспроизводимых deployments.
sberhome:
intents:
- slug: morning # optional, autogen из name (Cyrillic OK)
name: "Доброе утро"
home: "Мой дом" # optional, default: первый дом аккаунта
phrases:
- "доброе утро"
- "проснуться"
enabled: true
description: "Утренний сценарий" # optional
actions:
- type: ha_event_only # просто fire HA-event sberhome_intent
- type: tts # озвучивание через колонки
phrase: "Доброе утро!"
device_ids: ["speaker-id-1"]
- type: device_command # отправка команды устройству
device_id: "light-id-1"
attributes:
- key: on_off
type: BOOL
bool_value: true
- slug: bedtime_dacha
name: "Спокойной ночи (дача)"
home: "Дача" # сценарий пойдёт в дом «Дача»
phrases: ["спокойной ночи"]
actions:
- type: ha_event_onlyУказание дома (v5.3.0+):
home: "Мой дом"— резолв по имени дома (как видно в приложении «Салют!»). Регистр и trailing whitespace игнорируются.home_id: "..."— явный UUID (для опытных).- ничего — берётся default-дом (первый в списке аккаунта).
Если запрошенный home не найден среди реальных домов аккаунта —
intent попадает в report.failed, в логи пишется warning, в Sber
ничего не отправляется.
Поведение:
- Additive — YAML только создаёт/обновляет, не удаляет intent'ы созданные руками через UI или приложение «Салют!».
- Ownership marker — каждый созданный из YAML сценарий помечается в
descriptionпрефиксом🤖 HA-managed (sberhome): slug=<slug>— пользователь в приложении «Салют!» видит, что сценарий управляется HA, и знает, что правки будут перезаписаны. - Sync conflict — если пользователь отредактировал HA-managed сценарий в приложении «Салют!», следующий reload перезатрёт его YAML-версией. Этот выбор согласован архитектурой: YAML — единственный источник истины для интентов с маркером.
- Orphans — HA-managed сценарии в Sber без YAML-counterpart не удаляются автоматически (additive). В логи пишется warning; удалять руками через приложение «Салют!» если они больше не нужны.
После правки YAML — вызовите сервис sberhome.reload_intents через
Developer Tools → Services, без перезапуска HA. Он перечитает
configuration.yaml и применит изменения.
В качестве trigger в HA-автоматизации:
- trigger:
platform: event
event_type: sberhome_intent
event_data:
name: "Доброе утро"
trigger_type: PHRASES # только голосовое срабатывание
action:
- service: light.turn_on
target:
entity_id: light.bedroomPayload sberhome_intent event (что приходит из Sber):
name— имя сценария.scenario_id— UUID сценария (object_id).event_time— ISO-8601 UTC с микросекундами.type—SUCCESS/ERROR/CANCELLED.trigger_type—PHRASES(голос) /TIME(расписание) /DEVICE(sensor) /CONDITIONS/GEO_TIME/CHECK_DEVICE/CHECK_SCENARIO/null.home_id— UUID дома, где сработал сценарий.account_id— Sber-аккаунт.event_id— UUID события (для dedup).description— пользовательское описание (включая HA-managed маркер для YAML-managed сценариев).
Sber API не передаёт распознанный STT-текст (что именно сказал пользователь). Доступен только сам факт срабатывания + тип триггера. Чтобы различать «доброе утро» от «проснуться» — создавайте отдельные intent'ы под каждую фразу: HA-automation фильтрует по
name.
Поддерживаемые action-типы (v5.2.0+): ha_event_only, tts,
device_command. Расширения (regime_command, condition_branch и
т.п.) — в следующих релизах; до тех пор остаются доступны через UI.
Проект разделён на два слоя:
Чистый async Python-клиент Sber Gateway API без зависимостей от Home Assistant. Готов к выделению в отдельный PyPI-пакет.
from custom_components.sberhome.aiosber import (
SberClient, AttributeValueDto, AttrKey, ColorValue,
)
async def main():
async with await SberClient.from_companion_token("...") as client:
devices = await client.devices.list()
await client.devices.set_state(devices[0].id, [
AttributeValueDto.of_color(
AttrKey.LIGHT_COLOUR,
ColorValue(hue=120, saturation=100, brightness=80),
),
])Слои:
auth/— OAuth2 PKCE черезid.sber.ru+ companion token + auto-refresh.transport/— HTTP (httpx + retry + headers), WebSocket (reconnect + dispatch), lazy SSL.api/— 8 endpoint-доменов:DeviceAPI,GroupAPI,ScenarioAPI,PairingAPI(Matter),IndicatorAPI,InventoryAPI(OTA),LightEffectsAPI,ScenarioTemplatesAPI. Все доступны через единый фасадSberClient.dto/— 30+ dataclass'ов + 47 enum'ов.
CLI-примеры в examples/list_devices.py, set_color.py, ws_listen.py.
Тонкий слой поверх aiosber/. 15 платформ: light, switch, sensor,
binary_sensor, climate, cover, fan, humidifier, media_player,
number, select, event, button, vacuum, update.
coordinator.client — публичная точка входа во все Sber-API из любого
HA-кода (платформы, WS-эндпоинты, кастомные панели). Под капотом —
один SberClient instance, lazy-built поверх shared HttpTransport.
Layered architecture для bidirectional bridge с Sber-сценариями:
┌──────────────────────────────────────────────────────┐
│ UI: sberhome-intents-view + sberhome-intent-modal │ Lit + schema-driven
└──────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────┐
│ WS endpoints — sberhome/intents/{list,get,create, │ websocket_api/intents.py
│ update,delete,test,schema,devices_for_picker} │
└──────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────┐
│ IntentService — high-level CRUD + last_fired_at │ intents/service.py
└──────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────┐
│ IntentEncoder — IntentSpec ↔ Sber wire JSON │ intents/encoder.py
│ с forward-compat raw_extras для unknown полей │
└──────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────┐
│ ActionRegistry — extensibility hub │ intents/registry.py
│ + IntentSpec / IntentAction / FieldSpec │ intents/spec.py
└──────────────────────────────────────────────────────┘
▼
┌──────────────────────────────────────────────────────┐
│ ScenarioAPI (aiosber) — REST endpoints │ aiosber/api/scenarios.py
└──────────────────────────────────────────────────────┘
Добавить новый action_type (например IFTTT-webhook): одна запись в ACTION_TYPES + 2 функции (encode/decode), UI получит option автоматически.
Дispatcher для ловли срабатываний: coordinator._on_ws_scenario_widgets
подписан на WS-топик scenario_widgets, при UPDATE_WIDGETS push
дёргает /scenario/v2/event (history endpoint), фильтрует по
event_time > cursor, fire'ит sberhome_intent HA event для каждого
нового события.
- sber-mqtt-bridge — обратное направление: выставление HA-устройств в Сбер через MQTT-партнёрский API («Салют, включи лампу на кухне» управляет вашим HA-устройством).
- altfoxie/ha-sberdevices — оригинальная интеграция, откуда идёт авторизация.
MIT — см. LICENSE.