Предыдущие главы:

• Часть 1 — Мотивация
• Часть 2 — Установка + немного о моей системе

Прощу прощения за задержку в публикации статьи. Времена нынче не простые…

Оглавление

• Предисловие
• Настройки из админки
• Настройки через конфиг файлы
• Логи
  • Karaf console
  • Frontail – логи в браузер
• Заключение

Предисловие

В третьей публикации поговорим о настройке openHab и взаимодействии со внешними устройствами.

На этом этапе важно еще раз подчеркнуть, что являясь пожалуй наиболее гибкой среди подобных систем, openHab незбежно имеет и обратную сторону медали. А именно, для достижения продвинутого функционала потребуется весьма глубокое понимание происходящего как в самом openHab, так и умение конфигурировать операционную систему хоста (как привило какой-нибудь Linux), на котором, собственно, и бежит openHab. Но есть две хорошие новости. Первая заключается в том, что знания эти с большой степенью вероятности понадобятся не сразу. Общепринятые концепции разработки сложных систем всегда рекоммендуют постепенную, инкрементальную разработку, иначе говоря от простого к сложному. Так и здесь, изучая возможности системы и постепенно наращивая функционал умного дома, можно поэтапно накопить серьезный багаж знаний. Собственно в этом заключается вторая хорошая новость – практически вся необходимая информация широко представлена в сети. Потребуется лишь минимальное знание английского, для чтения тематических форумов.

openHab позволяет создавать кастомные графические интерфейсы. Впринципе там и, что называется “из коробки”, довольно много симпатичного функционала. Однако, ничего не мешает закастомизировать все донельзя, но это потребует познаний в CSS, angularJS и т.д.

Данная часть повествования начнется с простенького примера, возможно даже слишком простенького, просто чтобы показать концепцию конфигурирования openHab на базовом уровне. А вот следом сразу последуют  вещи сложнее и интереснее, в частности обещаная экосистема Xiaomi. Тем не менее, и этот простенький пример может пригодиться впоследствии, поэтому поигравшись, не удаляйте его.

Итак, приступим к настройке openHab. Традиционно, системы подобные openHab имеют как минимум два принципиально разных графических интерфейса. Первый – это админка, так называемый back end. Этот интерфейс используется для настройки и администрирования системы. Второй – это пользовательский интерфейс, front end, через который пользователи взаимодействуют с системой.

В случае openHab, система настолько разрослась, что существует целый ряд графических интерфейсов, на выбор. Задачу облегчает тот факт, что интерфейсы могут работать параллельно, а некоторые в определенной мере даже совмещают в себе и админку и пользовательский интерфейс. Например, заслуженно популярный Habpanel, но о нем позже.

В любом случае, здесь важно упомянуть, что новейшие версии openHab частично поддерживают конфигурирование новых устройств и наладку взаимодействия с ними через админку. Частично, потому что этот подход сработает лишь с простыми устройствами, вроде WiFi лампочки. Кроме того, он не лишен дополнительных недостатков, в виде низкой скорости процесса конфигурирования новых и существующих устройств, сложности резервного копирования конфигурации системы, невозможности создавать комплексные схемы взаимодействия и т.п. По сути, всякая продвинутая конфигурация системы производится классически, через текстовые конфигурационные файлы. А графическая админка используется для общего администрирования системы и контроля за правильностью составления файлов конфигурации.

Настройки из админки

В предыдущей части мы остановились на приветственной веб-морде:

Кликнув по PaperUI мы оказываемся в админке. Не вижу особого смысла тратить сейчас уйму времени на подробное описание каждого пункта админки – уверен, назначение большей части из них вполне понятно из названия. Ну и по мере повествования, мы поговорим о некоторых пунктах более подробно.

Пара слов о терминологии. Практически любое устройство или сервиc в opebHab начинается с установки так называемного байндинга (binding). Это программый модуль (add-on) реализующий поддержку того или иного устройсва или онлайн сервиса. После установки и настройки байндинга, можно добавить в систему устройство (или сервис), называемые в экосистеме openHab вещами (things). Каждая вещь предоставляет как минимум один канал для взаимодействия или передачи информации, называемые предметами (items). В официальной документации напечатано очень много букафф на эту тему. Я предлагаю наплевать на это, и сразу в бой. А в документацию лезть когда приключатся проблемы.

Итак, давайте попробуем добавить простейший binding. Классическим примером будет Astro Binding – сервис, показывающий положение Солнца и Луны по месту вашего жительства, а также уровни солнечной радиации впридачу. Этот binding хорош тем, что конфигурируется и из админки, и через файлы конфигурации, и впоследствии, скушные цифровые результаты его работы, можно превратить вот в такой прикольный виджет:

Эта штука в режиме почти реального времени показывает положение небесных тел по отношению к моему жилищу и тень, отбрасываемую им.

Итак, в PaperUI, отправляемся в меню Add-ons -> BINDINGS и ищем там Astro Binding. Жмем Install:

Далее, установим наше местоположение в настройках openHab. Кстати, этой информацией пользуются многие bindings, поэтому стоит произвести настройку в любом случае. Идем в меню Configuration -> System и промотав немного вниз находим Regional Settings, где нужно выставить язык, страну, часовой пояс и местоположение. Это можно сделать путем введения координат, или просто поставить флажок на карте:

Впринципе после этих манипуляций, openHab будет готов к работе с Astro Binding: новые вещи появится в инбоксе – Local Moon и Local Sun:

Как я уже упоминал, по идее, можно кликнуть по вещам в инбоксе и добавить их в систему. Но мы пойдем другим путем – через файлы конфигурации.

Настройки через конфиг файлы

Для начала нужно добраться до этих файлов. Они находятся по адресу /etc/openhab2 (верно для openHab версии 2). Я нахожу наиболее удобным заниматься редактированием файлов конфигурации с помощью современных редакторов, а так-же пользоваться преимущестрвами систем контроля версий (git и иже с ним). Проще всего это осуществить, расшарив папку с файлами конфига для доступа по сети, и работаться с ними удаленно.

Тут читателю возможно придется немного пошаманить и погуглить инструкции по установке samba (это пакет софта, позволяющий расшаривать папки и файлы). Но по сути мы его устанавливаем:

sudo apt-get install samba

И конфигурируем:

sudo nano /etc/samba/smb.conf

В открывшемся файле меняем значение workgroup на установленное в вашей сети (это не обязательно, но в случае правильной настройки позволит обращаться к расшареным ресурсам с помощью имени хоста), проматываем в конец файла и добавляем примерно следующие строки:

[openHAB2-conf]
comment=openHAB2 site configuration
path=/etc/openhab2
browseable=Yes
writeable=Yes
only guest=no
public=yes
create mask=0777
directory mask=0777

Примерно, потому что нужно еще создать в samba пользователя, и прописать его в эту шару тоже, но эти шаги есть в каждой инструкции в сети… Затем перезапускаем сервис samba для применения новых настроек:

sudo systemctl restart smbd

После этого, если все проделано верно, файлы будут доступны по сети.

Отправляемся в проводнике по адресу \\<server_address>\openHAB2-conf и видим набор папок с заветными конфигами:

Именно в этой, головной папке стоит создать репозиторий для контроля версий.

Начнем мы с конфигурирования вещей. Для этого откроем папку things, создадим там файл, например home.things и откроем его тектовым редактором. Текстовый редактор подойдет любой. Я долго пользовался Notepad++, но в какой-то момент перешел на Microsoft Visual Studio Code, поскольку он предлагает уникальные возможности редактирования файлов вообще, и файлов конфига openHab в частности, и это экономит уйму времени.

Добавим в home.things следующие строки:

astro:sun:home [ geolocation="37.51826894410237,144.99790407804505", interval=60 ]
astro:moon:home [ geolocation="37.51826894410237,144.99790407804505", interval=60 ]

Ну, ежу понятно, что geolocation это координаты, а interval, собственно, интервал обновления положения светил. Сохранив файл, мы определили вещь. В данном случае это не физическое устройство, а сервис.

Теперь эти вещицы появятся в списке Things в PaperUI:

Если теперь кликнуть по вещи, то можно увидеть полный список каналов взаимодействия items (в данном случае каналов получения информации) предоставляемых вещью. Иногда, как в данном случае, их немало:

Большое количество items не означает, что их нужно использовать все. Как раз наоборот, нужно использовать только те, что необходимы для решения поставленных задач. К примеру, выберем и определим наиболее интересные для нашей простой цели. Для этого идем в папку items и создаем файл home.items, в который поместим следующий код:

/* Astro */
Group		Astro
Number		Sun_Elevation		"Sun Elevation"			<sun>		(Astro)	{channel = "astro:sun:home:position#elevation"}
Number		Sun_Azimuth		"Sun Azimuth"			<sun>		(Astro)	{channel = "astro:sun:home:position#azimuth"}
DateTime	Sunrise_Time		"Sunrise [%1$tH:%1$tM]"		<sunrise>	(Astro)	{channel = "astro:sun:home:rise#start"}
DateTime	Sunset_Time		"Sunset [%1$tH:%1$tM]"		<sunset>	(Astro)	{channel = "astro:sun:home:set#start"}
Number		Moon_Elevation		"Moon Elevation"		<moon>		(Astro)	{channel = "astro:moon:home:position#elevation"}
Number		Moon_Azimuth		"Moon Azimuth"			<moon>		(Astro)	{channel = "astro:moon:home:position#azimuth"}
String		Moon_Phase		"Moon Phase"			<moon>		(Astro)	{channel = "astro:moon:home:phase#name"}
/* END OF Astro */

Далее, идет поле в <треугольных скобках>. Это поле определяет иконку для item. Можно выбрать из стандартного списка, можно прописать свои (займемся этим в дальнейшем). Иконки могут быть динамическими, к примеру иконка батарейки будет автоматически меняться от полной до пустой , в зависимости от значения item к которому она привязана. Кастомные иконки тоже можно научить такому поведению. Мы обязательно поговорим об этом.

Затем, в привычных (круглых скобках) можно определить группу, к которой принадлежит item. Сама группа, которая тоже является item, тоже должна быть определена. В нашем примере мы определили группу Astro, и далее поместили семь вещей в эту группу. Группирование удобно, потому что привносит логику, упрощает конфигурацию ГУИ и в некоторых случаях, позволяет совершать взаимодействие со всей группо сразу. К примеру, создав группу выключателей света, можно выключить их все сразу, одной коммандой.

Наконец в {фигурных скобках} определяется канал передачи данных. По сути сюда мы просто копируем строку нужного канала связи с вещью (из длиннющего скриншота выше).

Сохраняем home.items. Теперь новые items должны появиться в админке:

Ну и наконец, традиционно, создадим простейший ГУЙ, во фронт-энде под названием BasicUI, где отобразим наши items. Идем в папку sitemaps, где создаем файл home.sitemap со следующим содержанием:

sitemap home label="Main Menu" {
	Text label="Astronomical Data" icon="sun" {
		Text item=Sun_Elevation
		Text item=Sun_Azimuth
		Text item=Sunrise_Time
		Text item=Sunset_Time
		Text item=Moon_Elevation
		Text item=Moon_Azimuth
		Text item=Moon_Phase
	}
}

Сохраняем и отправляемся в браузере по адресу http://<server_address>:8080/basicui/app?sitemap=home:

Данные будут автоматически обновляться раз в минуту (мы определили это в конфигурации вещи). Как можно догадаться, не найдя определений иконок для items в sitemap, система использовала те, что определены для конкретных items в файле home.items. Т.е. конфиг sitemap может переопределять некоторые свойства item. К примеру, изменив

Text item=Sun_Elevation

на

Text item=Sun_Elevation icon=smiley

получаем:

А теперь поменяем

Number		Sun_Elevation		"Sun Elevation"			<sun>		(Astro)	{channel = "astro:sun:home:position#elevation"}

на

Number		Sun_Elevation		"Sun Elevation [%.1f °]"			<sun>		(Astro)	{channel = "astro:sun:home:position#elevation"}

в файле home.items. Результат:

Отформатировали стиль отображения числовой информации, как и обещано выше.

Ну и напоследок, заменим содержимое home.sitemap на:

sitemap home label="Main Menu" {
        Group item=Astro icon="sun"
}

Внешний вид нашего BasicUI не изменится. Т.е. мы можем использовать элементы группы по отдельности, или добавить в BasicUI всю группу сказу.

Эти простые примеры показывают всю гибкость и простоту конфигурирования BasicUI, items и things через текстовые конфиг файлы. Вместе с этим нужно помнить, что мы не раскрыли и малой доли потенциала и возможностей openHab и самое вкусное еще впереди.

Не пугайтесь делать ошибок. Каждый раз, когда вы сохраняете изменения в файлах конфига, openHab тщательно проверяет их, и применяет новые настройки только в случае, если файлы не содержат обшибок. Если же таковые имеются, то система сообщит об этом в логах и дальше, в зависимоти от характера проблем, либо просто проигнорирует кривой конфиг, либо ГУЙ станет выглядеть весьма коряво. Полностью порушить систему кривым конфигом мне лично еще не удавалось.

Давайте же немного поговорим о логах openHab. Это совершенно незаменимый инструмент, позволяющий разобраться в проблемах, когда что-то идет не так.

Логи

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

Когда на первых порах в моей системе была всего пара простых вещей, я не пользовался логами. Теперь в моей системе десятки вещей и сотни items, и я все еще не пользуюсь логами. Когда все работает штатно. Не пользуюсь. А зачем?

Другое дело когда что-то идет не так, когда вкривь и вкось. Тогда логи оказывают неоценимую помощь, а пару раз бывало, что без них вообще бы ничего не вышло.

Наиболее подробная информация о логах находится на официальном сайте. Рассмотрим наиболее важные аспекты.

Логи работы системы сохраняются системой в двух файлах:

events.lo
openhab.log

В зависимости от типа установки openHab они могут находиться либо по адресу /userdata/log либо /var/log/openhab2 (скорее всего вам повстречается второй вариант). Ничего не мешает натравить на эти файлы одну из утилит профессионального анализа лог файлов, вроде LogViewPlus к примеру. Круче этой утилиты на свете ничего нет.

Karaf console

Можно воспользоваться встроенными механизмами мониторинга openHab. В системе есть своя консоль, называемая Karaf, которая позволяет мониторить логи в режиме реального времени, выполнять разного рода команды и т.п.

Для того, чтобы зайти в Karaf, выполните следующую команду в консоли сервера openHab:

ssh -p 8101 openhab@localhost

В ответ на запрос авторизации, используйте дефолтную связку логин/пароль openhab:habopen.

Кстати, во время самого первого сеаса соединения, оно там вас может спросить, точно ли вы хотите впервые установить соединение с этим хостом, или шут с ним. Соглашайтесь (yes) и помните, что на медленных компах первое соединение может занять некоторое время. Последующие будут работать гладко.

Так. Залогинились и пришло время пялиться в логи. Тут есть несколько команд:

Полнейшая информация и примеры здесь.

По поводу уровней логирования, их существует несколько. Обычно, для того, чтобы разобраться в проблемах достаточно дефолтного уровня логирования – INFO. Реже может понадобиться переключиться на более подробное логирование, хотя объемы сохраняемых данных, ожидаемо, существенно возрастут и понадобится большее ментальное напряжение для их анализа.

Список уровней логирования:

Пример. Посмотрим что там у нас сейчас, введя log:tail:

Раз в минуту логируются события обновления значений наших items из примера описанного выше.

Поменяем уровень логирования для пакета smarthome.event.ItemStateChangedEvent:

log:set TRACE smarthome.event.ItemStateChangedEvent

Подождем немного, и опять сядем логам на хвост (log:tail):

Появилась новая, более низкоуровневая информация. Уже можно более детально поглядеть на подробности обмена данными.

Не забывайте, найдя в логах ответы на свои вопросы и решив проблему, поменять уровень логирования на дефолтный INFO. В данном случае:

log:set INFO smarthome.event.ItemStateChangedEvent

Frontail – логи в браузер

Мой излюбленный способ смотреть в логи openHab – через браузер. Излишне рассказывать, как это удобно. Сделать это можно с помощью утилиты frontail.

Ставим необходимые приложения:

sudo apt-get install nodejs
sudo apt-get install npm

Затем сам frontail:

sudo npm i frontail -g

Создадим новый системный сервис:

cd /lib/systemd/system/
sudo nano frontail.service

И в открывшийся редактор вставим следующий скрипт:

#!/bin/sh -

[Unit]
Description=Frontail

[Service]
ExecStart=/usr/local/bin/frontail --ui-highlight --theme dark /var/log/openhab2/openhab.log /var/log/openhab2/events.log /var/log/openhab2/zwave.log
Restart=always
User=openhab
Group=openhab

[Install]
WantedBy=multi-user.target
Alias=frontail.service

Возможно, вам нужно будет поменять значения User и Group на значения тех, из под которых бежит openHab на вашей системе. Сохраняем, и следом выполняем следующие команды:

sudo chmod 644 /lib/systemd/system/frontail.service
sudo systemctl daemon-reload
sudo systemctl enable frontail.service
sudo systemctl start frontail.service

Если все проделано правильно, то пройдя в браузере по адресу http://<server_addres>:9001 мы увидим заветные логи:

Если нет, то выполняйте:

sudo systemctl status frontail.service

И дебажьте…

По желанию можно добавить цветовых гамм и стилей. Это делается путем создания файла openhab.json по адресу /usr/local/lib/node_modules/frontail/preset/.

К примеру:

{
  "words": {
    "[ERROR]": "color: red;",
    "[WARN ]": "color: orange;",
    "[INFO ]": "color: green;",
    "Node is DEAD": "color: red;",
    "GroupItemStateChangedEvent": "color: #0026FF; font-weight: bold;",
    "ItemStateChangedEvent": "color: #ADD8E6;",
    "ItemCommandEvent]": "color: #00137F;",
    "hingStatusInfoChangedEvent": "color: #007F46;",
    "ON": "color: green; font-weight: bold;",
    "OFF": "color: red; font-weight: bold;",
    "received command": "color: yellow;"
  },
  "lines": {
    "/var/log/openhab2/openhab.log": "text-align: right; font-size: 1.5em; font-weight: bold; border-top: 2px solid #F8F8F8;",
    "/var/log/openhab2/events.log": "text-align: right; font-size: 1.5em; font-weight: bold; border-top: 2px solid #F8F8F8;",
    "ERROR": "background-color: #F3BFBF;",
    "model.script": "background-color: #A6CFFD; font-weight: bold;"
  }
}

Затем нужно остановить сервис:

sudo systemctl stop frontail.service

Теперь нужно поменять строку начинающуюся на ExecStart в файле frontail.service на:

ExecStart=/usr/local/bin/frontail --ui-highlight --ui-highlight-preset /usr/local/lib/node_modules/frontail/preset/openhab.json --theme dark /var/log/openhab2/openhab.log /var/log/openhab2/events.log /var/log/openhab2/zwave.log

Сохраняем файл и снова выполняем:

sudo systemctl daemon-reload
sudo systemctl start frontail.service

Обновляем браузер:

Тадам! Цвета! Предлагаю читателю пошаманить цветами на свой вкус.

Заключение

Масштабный получился материал. Но это основа всего того, что мы будем делать дальше. В следующей части я планирую рассказать, как уже неоднократно обещал, о подключении устройств Xiaomi. Китайцы недавно понаворотили дел, поэтому в процессе подключения могут потребоваться новые, не слишком интуитивно понятные шаги. А могут и не потребоваться, как уж повезет. Но, где наша не пропадала? Решение всегда находится. Я все расскажу и покажу.

После Xiaomi я планирую рассказать о некоторых самопальных девайсах, которые я использую. Ну и затем HabPanel – там тоже немало интересного.

До встречи.