Написание своего binding для OpenHab 2 или Eclipse Smarthome

При работе с OpenHab или Eclipse SmartHome рано или поздно возникает потребность в разработке собственного байндинга. Особенно актуально это для разработчиков и производителей электроники, которые хотят предоставить интерфейс интеграции для своих устройств в систему умного дома. К сожалению в сети нет материалов по данному вопросу на русском языке.  Расскажем, как сделать свой байндинг.

Для разработки модулей OpenHab 2 и Eclipse SmartHome (в том числе и binding) потребуется установленная IDE на базе Eclipse. Так как проект уже несколько лет входит в сообщество Eclipse, то и среда разработки используется их. По этой причине установка не вызывает никаких проблем, используется стандартный установщик Eclipse. Нужно лишь при установке выбрать одну или несколько составляющих в расширенном режиме («Advanced mode»). При необходимость существует пошаговая инструкция от OH2.
add-ons checkbox
В зависимости от того насколько старую версию Eclipse вы будете устанавливать будут подргужены все необходимые исходные коды из git’а проекта. В более новых загрузка происходит уже после установки IDE на диск, в старых установка не завершается пока не будет сделана локальная копия репозитария. Такой подход позволяет значительно сэкономить время на установку в новых версиях и сразу приступить к работе.

Для сборки проектов используется Maven от Apache. Поэтому его требуется также установить перед началом работы. Также потребуется JDK версии 8 (1.8) в исходниках и пакет для разработки (в нём находятся утилиты для тестирования и анализа кода, которые используются на конечных этапах сборки). В OpenSUSE установка всего необходимого осуществляется следующей командой:

zypper install Java-1_8_0-openjdk-src java-1_8_0-openjdk-devel maven

Первоначально необходимо сформировать заготовку проекта байндинга. Для это необходимо запустить скрипт из папки git/smarthome/extensions/binding с именем binding в качестве аргумента. Здесь и далее будем использовать «__name__» в качестве шаблона имени разработки, чтобы легко и наглядно отличать эти места.

create_esh_binding_skeleton.sh __name__

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

[INFO] —————————————————————————-
[INFO] Using following parameters for creating project from Archetype: org.eclipse.smarthome.archetype.binding:0.10.0-SNAPSHOT
[INFO] —————————————————————————-
[INFO] Parameter: groupId, Value: org.openhab.binding
[INFO] Parameter: artifactId, Value: org.openhab.binding.__name__
[INFO] Parameter: version, Value: 2.3.0-SNAPSHOT
[INFO] Parameter: package, Value: org.openhab.binding.__name__
[INFO] Parameter: packageInPathFormat, Value: org/openhab/binding/__name__
[INFO] Parameter: bindingIdCamelCase, Value: __name__
[INFO] Parameter: vendorName, Value: openHAB
[INFO] Parameter: namespace, Value: org.openhab
[INFO] Parameter: author, Value: __author__
[INFO] Parameter: groupId, Value: org.openhab.binding
[INFO] Parameter: startYear, Value: 2014
[INFO] Parameter: version, Value: 2.3.0-SNAPSHOT
[INFO] Parameter: bindingId, Value: __name__
[INFO] Parameter: package, Value: org.openhab.binding.__name__
[INFO] Parameter: artifactId, Value: org.openhab.binding.__name__
[INFO] Parent element not overwritten in /home/__username__/OH_binding/openhab2-master/git/openhab2-addons/addons/binding/org.openhab.binding.__name__/pom.xml
[WARNING] Don’t override file /home/__username__/OH_binding/openhab2-master/git/openhab2-addons/addons/binding/org.openhab.binding.__name__/pom.xml
[INFO] Project created from Archetype in dir: /home/__username__/OH_binding/openhab2-master/git/openhab2-addons/addons/binding/org.openhab.binding.__name__
[INFO] ————————————————————————
[INFO] BUILD SUCCESS
[INFO] ————————————————————————
[INFO] Total time: 01:56 min
[INFO] Finished at: 2018-01-04T18:09:30+03:00
[INFO] Final Memory: 26M/223M
[INFO] ————————————————————————

Как видно в папке с установленным OH2 (/home/__username__/OH_binding/openhab2-master/git/openhab2-addons/addons/binding/org.openhab.binding.__name__/)  была сформирована заготовка.

Её можно импортировать в качестве проекта в Eclipse через меню File->Import->General->Existing Projects into Workspace, указав путь выше.

К сожалению по какой-то непонятной причине она не собирается из коробки. Требуется доработать конфигурацию для сборки. Тут есть 2 пути: через консоль и редактирование текстовых файлов и через графический интерфейс силами самого Eclipse (он умеет преобразовывать файлы конфигурации в меню с галочками). Рассмотрим первый вариант, так как второй при наличии описания первого не вызывает никаких сложностей.

В build.properties указаны папки, которые необходимо собрать. В нём указана необходимость сборки папки NOTICE. Однако, самой папки в шаблоне нет. Поэтому её необходимо создать или скорректировать последнюю строку.

source..=src/main/java/
output..=target/classes
bin.includes=META-INF/,\
.,\
OSGI-INF/,\
ESH-INF/,\
NOTICE/,\

после этого можно запускать на сборку проекта командой

mvn clean install

Процесс компиляции скорее всего завершится удачно, однако на этапе анализа могут возникнуть ряд проблем.

Если получите сообщение об ошибке в консоли:

[ERROR] org.openhab.binding.__name__.handler.****.java:[4]

Line does not match expected header line of ‘^ \* All rights reserved\. This program and the accompanying materials$’.

то необходимо заменить шапки (первые строки исходного кода) в соответствующих файлов на старую версию. Так пока в регулярных выражениях на которые происходит проверка используется старый шаблон, а в шаблонах в git уже лежит новая версия шапки. Должны пофиксить в ближайшее время заменой лицензии Eclipse Public License на новую версию 2.0 в регулярных выражениях, но пока вопрос решается таким образом. Меняем

/**
* Copyright (c) 2014-2018 by the respective copyright holders.
*
* See the NOTICE file(s) distributed with this work for additional
* information regarding copyright ownership.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0
*
* SPDX-License-Identifier: EPL-2.0
*/

на

/**
* Copyright (c) 2018-2018 by the respective copyright holders.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*/

Ошибка отсутсвия файла

[ERROR] .binding.__name__/build.properties:[0]
about.html file must be added to the bin.includes property

Исправляется правкой файла build.properties. Нужно добавить строку:

source..=src/main/java/
output..=target/classes
bin.includes=META-INF/,\
.,\
OSGI-INF/,\
ESH-INF/,\
NOTICE,\
About.html

В результате в папке /target/ Появится jar-файл соответствующий имени проекта и версии OH и самой сборки — org.openhab.binding.__name__-2.3.0-SNAPSHOT.jar. Это файл уже можно поместить в папке байндингов установленного OH2 или ESH и он будет работать. Рассмотрим более подробно структуру шаблона, чтобы понять какие функции и параметры необходимо определить.

В ESH-INF/binding/binding.xml описывается общая информация по биндингу.

<name>__name__ Binding</name>
<description>This is the binding for __name__.</description>
<author>__author__</author>

В папке ESH-INF/i18n/ хранятся переводы на различные языки, для русского необходимо определить ru_RU.

В рамках байндиинга при необходимости можно создать свой тип Thing. Его описание должно находиться в папке /ESH-INF/thing/ :

<!— Sample Thing Type —>
<thing-type id=»sample»>
<label>__name__ Binding Thing</label>
<description>Sample thing for __name__ Binding</description>

<channels>
<channel id=»channel1″ typeId=»sample-channel»/>
</channels>
</thing-type>

<!— Sample Channel Type —>
<channel-type id=»sample-channel»>
<item-type>__name__Item</item-type>
<label>__name__ Binding Channel</label>
<description>Sample channel for __name__ Binding</description>
</channel-type>

Весь основной код биндинга (функция обработчика) находится в /main/java/org/openhab/binding/__name__/handler/__name__Handler.java

@Override
public void handleCommand(ChannelUID channelUID, Command command) {
if (channelUID.getId().equals(CHANNEL_1)) {
// TODO: handle command
}
}

В этом же файле расположена функция инициализации Thing:

@Override
public void initialize() {
// TODO: Initialize the thing. If done set status to ONLINE to indicate proper working.
// Long running initialization should be done asynchronously in background.
updateStatus(ThingStatus.ONLINE);
}

Постоянные, такие как идентификатор биндига, типы и список Thing в нём, а также список каналов в биндинге описываются в /main/java/org/openhab/binding/__name__/__name__BindingConstants.java

private static final String BINDING_ID = «__name__»;

// List of all Thing Type UIDs
public static final ThingTypeUID THING_TYPE_SAMPLE = new ThingTypeUID(BINDING_ID, «sample»);

// List of all Channel ids
public static final String CHANNEL_1 = «channel1»;

 

Последним файлом, который необходимо описать является фабрика по созданию Thing’ов. Это необходимо для соответствия стандартам OSGi https://ru.wikipedia.org/wiki/OSGi . В данном файле описываются какие функции используются для создания и обработки Thing’ов. OpenHab (Eclipse SmartHome) запускает фабрику каждый раз, когда Thing добавляется в систему. Располагается файл по пути /main/java/org/openhab/binding/__name__/internal/__name__HandlerFactory.java

private static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Collections.singleton(THING_TYPE_SAMPLE);

@Override
public boolean supportsThingType(ThingTypeUID thingTypeUID) {
return SUPPORTED_THING_TYPES_UIDS.contains(thingTypeUID);
}

@Override
protected @Nullable ThingHandler createHandler(Thing thing) {
ThingTypeUID thingTypeUID = thing.getThingTypeUID();

if (thingTypeUID.equals(THING_TYPE_SAMPLE)) {
return new __name__Handler(thing);
}

return null;
}

После доработки соответствующих файлов необходимо заново пересобрать проект через maven.

В этой статье мы рассмотрели действия необходимые и достаточные для начала разработки своего binding для OpenHab 2 или Eclipse Smarthome, а также рассмотрели структуру проекта и основные части кода, которые необходимо реализовать для полноценной разработки. Как видно выше всё достаточно просто, однако отстутствие документации и руководств на русском языке останавливало многих, это видно по истории поисковых запросов на крупнейших поисковиках.

 

Написание своего binding для OpenHab 2 или Eclipse Smarthome: Один комментарий

Добавить комментарий

Заполните поля или щелкните по значку, чтобы оставить свой комментарий:

Логотип WordPress.com

Для комментария используется ваша учётная запись WordPress.com. Выход / Изменить )

Фотография Twitter

Для комментария используется ваша учётная запись Twitter. Выход / Изменить )

Фотография Facebook

Для комментария используется ваша учётная запись Facebook. Выход / Изменить )

Google+ photo

Для комментария используется ваша учётная запись Google+. Выход / Изменить )

Connecting to %s