Дома и сайдкар

Где живёт дом

Дом — это план, устройства на нём, группы, вещи и настройки показа. Он хранится в сайдкаре — службе рядом с Home Assistant. Приложения и браузеры берут дом оттуда и туда же пишут правки.

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

Кроме дома, сайдкар хранит модели и текстуры (склад файлов), доступы, журнал, чат и тревоги.

Несколько домов

На одном сайдкаре и одном Home Assistant может жить несколько домов: квартира, дача, баня. У каждого свой план, а устройства Home Assistant общие. В подборщиках сущности чужих домов уходят под отдельную кнопку «В других домах», чтобы не мешаться со своими.

Список домов сайдкара ведётся на сервере. При первом запуске заводится хотя бы один дом. Новый дом на сайдкар добавляет тот, кто ставил стек: кнопки «завести дом на сервере» в приложении нет.

Доступ открывает выбранные дома: гостю можно дать дачу и не давать квартиру. См. Доступы и уровни.

Дома в приложении

Настройки → Дом → Дома. Список домов на этом устройстве. У каждого свой план и своё подключение; переключение меняет и то, и другое.

Кнопка	Что делает
Выбор в списке	Открыть дом. Сразу, без «применить»
Имя	Переименовать. У открытого дома название уезжает на все его устройства
Убрать	Убрать дом с этого устройства. В сайдкаре и Home Assistant ничего не меняется
Добавить дом	Новый дом с демонстрационным планом, подключение вводится следом
Дом из файла	Новый дом из файла .json или .homer

Если доступ открывает несколько домов одного сайдкара, ниже появляется блок «Планы этого сайдкара». Открыть заводит дом в списке с тем же адресом и секретом сайдкара: знакомиться заново не нужно.

В веб-версии дома переключаются выпадающим списком в шапке.

Сайдкар дома

Настройки → Доступ → Сайдкар дома.

Поле	Что вписать
Домашний адрес	Адрес сервера дома в домашней сети, порт 8730. Пусто — приложение возьмёт адрес Home Assistant с портом 8730
Внешний адрес	Адрес через обратный прокси, для тех, кто не дома. Пусто — снаружи дом недоступен никому

Проверить спрашивает сайдкар, отвечает ли он и кто вы для него. Если сайдкар сам знает свои адреса, он подставит их в пустые поля — проверьте и нажмите Сохранить.

Ниже на той же карточке — вход в дом: Стать владельцем или Принять приглашение. Если вход уже есть — приглашения, доступы и журнал. Подробнее — Доступы и уровни.

Адрес и токен Home Assistant

Настройки → Дом → Адрес и токен HA. Нужны владельцу один раз, чтобы стать владельцем. Остальным устройствам, вошедшим через сайдкар, эти поля не нужны: план, свет и прогулка идут через сайдкар. Гостю учётку в Home Assistant не выдают вовсе.

Место дома

Настройки → Дом → Место дома → На карте. В веб-версии: Правка → Дом: название, тариф, шаг, место…

По координатам считается высота солнца, по повороту дома — в какие окна оно светит. Пока точка не задана, берутся координаты сервера Home Assistant.

• Тап по карте ставит дом в точку.
• Ручку ↻ тяните, чтобы повернуть силуэт дома вдоль улиц и соседних домов на схеме.
• Я здесь — точка по геолокации устройства.
• Север вверх сбрасывает поворот.
• Забыть точку возвращает координаты Home Assistant.
• Поле широта, долгота → Туда переносит точку по числам, например 55.75, 37.62.

Подложка карты: ключ MapTiler

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

1. Зарегистрируйтесь на cloud.maptiler.com — бесплатного плана хватает на личный дом.
2. Скопируйте ключ в Account → API keys.
3. В Месте дома нажмите Вписать ключ (или Ключ карты, если ключ уже есть), вставьте и нажмите Сохранить.

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

Тайлы MapTiler браузер и приложение берут у MapTiler сами, с api.maptiler.com: условия MapTiler Cloud запрещают брать их через свой сервер (прокси) и хранить на нём без отдельного договора. Хранить квадраты можно только в кэше самого устройства — так и сделано. Поэтому ключ MapTiler сервер отдаёт тем, кто правит дом, и его стоит ограничить в кабинете MapTiler (Account → API keys → ключ → Allowed HTTP origins): впишите адрес веб-версии дома. Приложение для Android шлёт запросы без Origin, поэтому, если карта нужна и в нём, добавьте в список ? («неизвестный источник») — или заведите приложению отдельный ключ. Подстраховка от чужих запросов — лимит расходов в кабинете MapTiler: на бесплатном плане сверх лимита ключ просто перестаёт работать до следующего месяца.

Другой провайдер — шаблон адреса тайлов 256 px с {z}, {x}, {y} и {key} на месте ключа, плюс подпись провайдера. Пустой шаблон возвращает MapTiler Streets. Тайлы своего провайдера идут через сервер Хомера: он подставляет ключ в шаблон, качает квадрат и отдаёт его приложению и браузеру, так что ни ключ, ни шаблон к ним не попадают — их видит только владелец в окне Ключ карты (ключ — точками, его можно только заменить). Сервер хранит квадраты на своём диске — не больше 200 МБ на все дома и не дольше, чем разрешают заголовки провайдера (без них — 30 дней); при смене ключа или шаблона кэш дома стирается. Ограничения:

• адрес — только https, без логина и пароля в адресе;
• адреса локальной сети не принимаются (localhost, 192.168.…, 10.…, .local, имена без точки и т. п.), и имя, которое DNS разворачивает в такой адрес, сервер тоже не откроет: иначе через сервер Хомера можно было бы заглянуть в домашнюю сеть;
• не больше 20 квадратов в секунду на один доступ (в начале — запас в 240);
• тайлы tile.openstreetmap.org не принимаются: правила OpenStreetMap запрещают их приложениям, которые продаются;
• шаблон на *.maptiler.com — это MapTiler: тайлы идут напрямую, как выше.

Если провайдер не принимает ключ (ответ 401 или 403), поверх карты появляется «Ключ карты не принят — проверьте его в «Месте дома»», а владельцу — кнопка Ключ карты.

У MapTiler в углах карты — его логотип (ссылка на maptiler.com, обязателен на бесплатном плане) и подпись «© MapTiler» и «© OpenStreetMap contributors» со ссылками на их страницы авторских прав — так требуют правила атрибуции MapTiler. У своего провайдера — только текстовая подпись (или его адрес, если подпись не задана).

Копия и перенос дома

В приложении: Настройки → Файлы → Конфигурация дома. В веб-версии: Настройки → Файлы → Дом файлом.

Кнопка	Что получится
Экспорт	Один JSON: план, устройства, группы и пресеты света
С вещами	Архив .homer: тот же план плюс текстуры и модели. Поднимается на чистом устройстве без интернета
Импорт	Заменяет план открытого дома целиком. Пресеты из файла пишутся в Home Assistant
Копия со склада	Архив .homer, собранный сайдкаром: в нём и вещи, которые прислал гость-редактор, и настройки Homer и Home Assistant. Только владельцу

Галочка Целиком (только владельцу) добавляет в тот же файл .json или .homer настройки Homer и Home Assistant — см. Дом целиком.

Приложение и веб-версия читают файлы друг друга.

Файл из приложения — ключ от дома

В экспорт из приложения попадают адрес и токен Home Assistant: так дом поднимается на другом устройстве одним действием. Не пересылайте такой файл в мессенджере и не кладите в общую папку. В файле из браузера адреса и токена нет.

Перед большой правкой

Сохраните Копию со склада. Это полная копия дома со всеми файлами, и импортом она возвращается целиком.

Дом целиком

План, пресеты и вещи — не весь дом: после переезда на новый сервер или переустановки Home Assistant зоны, имена и автоматизации приходилось заводить заново. Галочка Целиком при экспорте (приложение и веб-версия) кладёт в файл ещё и настройки:

Откуда	Что ложится в файл
Homer	Слова пробуждения и голоса колонок, небо, распорядок сна и другие настройки дома — только по списку разрешённых
Home Assistant	Метки, этажи и зоны, хелперы, имена, зоны и алиасы устройств и сущностей, автоматизации, скрипты и сцены из интерфейса, пакеты homer_*.yaml

Что в файл не попадает:

• Токены и ключи — Telegram, Music Assistant, Яндекс, учётка Home Assistant, пинкод колонок, ключи провайдеров и карты, адреса этой машины. Ключ, подложенный в файл руками, импорт отклоняет: через файл от друга нельзя подсунуть серверу чужой токен.
• Интеграции — Zigbee, Яндекс и другие: у них ключи и железо. В файле только их список, и импорт называет, каких не хватает — поставьте их в Home Assistant, лучше до импорта.
• Автоматизации из YAML — экспорт называет, сколько их осталось за бортом.

Импорт сначала показывает отчёт: что заведётся, что поменяется, что не ляжет и почему. Пишет только после «да». Внутренние id у нового Home Assistant другие, поэтому устройства находятся по железу — адресу Zigbee (ieee) и MAC. Сущности, получившей после переустановки новый entity_id, возвращается прежний: на него ссылаются план, автоматизации и сцены из того же файла.

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

Копии дома на сервере

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

В приложении: Настройки → Файлы → Копии дома. В веб-версии: Настройки → Файлы → Копии дома. Возвращает только владелец.

Откат правки

Правку плана можно применить с подстраховкой.

• В веб-версии при правке есть три способа сохранить: Применить сразу, Применить сразу с откатом через 10 мин и, если вы не владелец, Сохранять черновиком.
• С откатом над планом у всех висит плашка с таймером. Владелец жмёт Оставить — правка остаётся. Не нажал за 10 минут — дом возвращается сам. Вернуть сейчас откатывает сразу.
• Черновик дом не меняет. Владелец видит плашку, смотрит план с подсвеченными изменениями и жмёт Принять, Принять на проверку (10 мин) или Отклонить. Обсудить пишет вопрос по правке в чат дома.

Сайдкар хранит и последние десять принятых версий дома. Это страховка на случай конфликта; кнопки возврата к ним в приложении нет.