Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Initial contribution of Homie Binding #1741

Closed
wants to merge 7 commits into from
Closed
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions addons/binding/org.openhab.binding.homie/.classpath
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove this file from the changeset.
I think we should have them in global .gitignore file, but for now
the best thing we can do is to create an ./git/info/exclude file with the following entries:

.classpath
.project
/target/

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I disagree with you. The classpath is necessary especially for projects that are using additional libraries. If you remove it you will have to recreate it each time you add this project to an Eclipse workspace.

<classpath>
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8"/>
<classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/>
<classpathentry kind="src" path="src/main/java/"/>
<classpathentry exported="true" kind="lib" path="lib/org.eclipse.paho.client.mqttv3-1.1.0.jar"/>
<classpathentry exported="true" kind="lib" path="lib/commons-lang3-3.5.jar"/>
<classpathentry kind="output" path="target/classes"/>
</classpath>
39 changes: 39 additions & 0 deletions addons/binding/org.openhab.binding.homie/.project
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<?xml version="1.0" encoding="UTF-8"?>

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove this file from the changeset.

Copy link
Contributor

@MHerbst MHerbst Jan 30, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is necessary too when this project is added to an Eclipse workspace. If you look into the existing projects, you will see that all contain a .project and .classpath.

<projectDescription>
<name>org.openhab.binding.homie</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.jdt.core.javabuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.pde.ManifestBuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.pde.SchemaBuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.pde.ds.core.builder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.m2e.core.maven2Builder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.m2e.core.maven2Nature</nature>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove this nature.

<nature>org.eclipse.pde.PluginNature</nature>
<nature>org.eclipse.jdt.core.javanature</nature>
</natures>
</projectDescription>
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
eclipse.preferences.version=1

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if whole .settings folder should be even committed here :)

encoding/<project>=UTF-8
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
eclipse.preferences.version=1
org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.8
org.eclipse.jdt.core.compiler.compliance=1.8
org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
org.eclipse.jdt.core.compiler.problem.enumIdentifier=error
org.eclipse.jdt.core.compiler.source=1.8
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
activeProfiles=
eclipse.preferences.version=1
resolveWorkspaceProjects=true
version=1
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?>
<binding:binding id="homie" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:binding="http://eclipse.org/smarthome/schemas/binding/v1.0.0"
xsi:schemaLocation="http://eclipse.org/smarthome/schemas/binding/v1.0.0 http://eclipse.org/smarthome/schemas/binding-1.0.0.xsd">

<name>Homie Binding</name>
<description>This is the binding for Homie devices, using the Homie MQTT convention.</description>
<author>Michael Kolb</author>

<config-description>
<parameter name="mqttbrokerurl" type="text" required="true">
<label>MQTT Broker URL</label>
<description>MQTT Broker URL in the format "tcp://myBrokerHost:1883"</description>
<default>tcp://broker:1883</default>
</parameter>

<parameter name="basetopic" type="text" required="true">
<label>MQTT base topic</label>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The formatting looks incorrect. XML files should be indented using tabs according to our code formatter. Can you please reformat.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

<description>topic under which all your devices are located. If e.g. your device sends to homie/mydevice-1/$online, your basetopic is "homie/"</description>
<default>homie</default>
</parameter>
</config-description>


</binding:binding>
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# binding
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove this file since you did not change anything

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed

binding.homie.name = <Your localized Binding name>
binding.homie.description = <Your localized Binding description>

# thing types
thing-type.homie.sample.label = <Your localized Thing label>
thing-type.homie.sample.description = <Your localized Thing description>

# channel types
channel-type.homie.sample-channel.label = <Your localized Channel label>
channel-type.homie.sample-channel.description = <Your localized Channel description>
168 changes: 168 additions & 0 deletions addons/binding/org.openhab.binding.homie/ESH-INF/thing/bridge.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
<?xml version="1.0" encoding="UTF-8"?>
<thing:thing-descriptions bindingId="homie" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:thing="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0"
xsi:schemaLocation="http://eclipse.org/smarthome/schemas/thing-description/v1.0.0 http://eclipse.org/smarthome/schemas/thing-description-1.0.0.xsd">


<thing-type id="homieDeviceV2">
<label>Homie Device</label>
<description>This thing represents a Homie Device that complies with the Homie MQTT Convention V2.0.0</description>

<channels>
<channel id="homie" typeId="homie-channel">
<properties>
<property name="topic_suffix">$homie</property>
</properties>
</channel>

<channel id="online" typeId="online-channel">
<properties>
<property name="topic_suffix">$online</property>
<property name="thing_state_indicator">online</property>
</properties>
</channel>

<channel id="name" typeId="name-channel">
<properties>
<property name="topic_suffix">$name</property>
</properties>
</channel>

<channel id="localip" typeId="localip-channel">
<properties>
<property name="topic_suffix">$localip</property>
</properties>
</channel>
<channel id="mac" typeId="mac-channel">
<properties>
<property name="topic_suffix">$mac</property>
</properties>
</channel>

<channel id="stats_uptime" typeId="stats-uptime-channel">
<properties>
<property name="topic_suffix">$stats/uptime</property>
</properties>
</channel>
<channel id="stats_signal" typeId="stats-signal-channel">
<properties>
<property name="topic_suffix">$stats/signal</property>
</properties>
</channel>
<channel id="stats_interval" typeId="stats-interval-channel">
<properties>
<property name="topic_suffix">$stats/interval</property>
</properties>
</channel>
<channel id="fw_name" typeId="fw-name-channel">
<properties>
<property name="topic_suffix">$fw/name</property>
</properties>
</channel>
<channel id="fw_version" typeId="fw-version-channel">
<properties>
<property name="topic_suffix">$fw/version</property>
</properties>
</channel>
<channel id="fw_checksum" typeId="fw-checksum-channel">
<properties>
<property name="topic_suffix">$fw/checksum</property>
</properties>
</channel>
<channel id="implementation" typeId="implementation-channel">
<properties>
<property name="topic_suffix">$implementation</property>
</properties>
</channel>
</channels>
</thing-type>



<channel-type id="homie-channel" advanced="true">
<item-type>String</item-type>
<label>Homie specification Version</label>
<description>Version of the Homie convention the device conforms to</description>
<state readOnly="true" />
</channel-type>

<channel-type id="online-channel" advanced="true">
<item-type>Switch</item-type>
<label>Online</label>
<description>Indicates whether the device is online or not</description>
<state readOnly="true" />
</channel-type>

<channel-type id="name-channel" advanced="true">
<item-type>String</item-type>
<label>Device Name</label>
<description>The name of the device</description>
<state readOnly="true" />
</channel-type>

<channel-type id="localip-channel" advanced="true">
<item-type>String</item-type>
<label>Device IP</label>
<description>Current IP address of the device</description>
<state readOnly="true" />
</channel-type>

<channel-type id="mac-channel" advanced="true">
<item-type>String</item-type>
<label>Device MAC</label>
<description>MAC address of the device</description>
<state readOnly="true" />
</channel-type>

<channel-type id="stats-uptime-channel" advanced="true">
<item-type>Number</item-type>
<label>Uptime</label>
<description>Time in seconds since the device came online</description>
<state pattern="%d s" readOnly="true" />
</channel-type>

<channel-type id="stats-signal-channel" advanced="true">
<item-type>Number</item-type>
<label>Signal</label>
<description>Signal level in percent. Might be not supported by wired devices</description>
<state pattern="%d %%" readOnly="true" />
</channel-type>

<channel-type id="stats-interval-channel" advanced="true">
<item-type>Number</item-type>
<label>Update Interval</label>
<description>Interval (in seconds) at which the uptime and signal are refreshed</description>
<state pattern="%d s" readOnly="true" />
</channel-type>

<channel-type id="fw-name-channel" advanced="true">
<item-type>String</item-type>
<label>Firmware Name</label>
<description>Name of the firmware running on the device</description>
<state readOnly="true" />
</channel-type>

<channel-type id="fw-version-channel" advanced="true">
<item-type>String</item-type>
<label>Firmware Version</label>
<description>Version of the firmware running on the device</description>
<state readOnly="true" />
</channel-type>

<channel-type id="fw-checksum-channel" advanced="true">
<item-type>String</item-type>
<label>Firmware Checksum</label>
<description>MD5 checksum of the firmware running on the device</description>
<state readOnly="true" />
</channel-type>

<channel-type id="implementation-channel" advanced="true">
<item-type>String</item-type>
<label>Implementation ID</label>
<description>An identifier for the Homie implementation </description>
<state readOnly="true" />
</channel-type>



</thing:thing-descriptions>
26 changes: 26 additions & 0 deletions addons/binding/org.openhab.binding.homie/META-INF/MANIFEST.MF
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Homie Binding
Bundle-SymbolicName: org.openhab.binding.homie;singleton:=true
Bundle-Vendor: openHAB
Bundle-Version: 2.0.0.qualifier
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Version bump to 2.1.0-SNAPSHOT

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

Bundle-RequiredExecutionEnvironment: JavaSE-1.8
Bundle-ClassPath: .,lib/org.eclipse.paho.client.mqttv3-1.1.0.jar,lib/commons-lang3-3.5.jar
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use the build in commons lang

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. As far as I know, there's only commons.lang build in, and not commons.lang3.
  2. This would mean a complete reimplementation of the connection class and its architecture.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. I opened an issue for that, but are you using anything specific in this case? Upgrading commons.lang to commons.lang3 eclipse-archived/smarthome#3522
  2. I did not check the exact impact but the idea of the transport bundle is that not all bindings have to duplicate the transport handling and drag along there own jar's. if you require changes in the transport bundle you can of course discuss/suggest them and create a PR

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be awesome to use the eclipse smarthome io.transport.mqtt bundle and the MqttService instead

Import-Package:
com.google.common.collect;version="10.0.1",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do not enforce versions

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

org.eclipse.smarthome.config.core,
org.eclipse.smarthome.config.discovery,
org.eclipse.smarthome.core.library.types,
org.eclipse.smarthome.core.thing,
org.eclipse.smarthome.core.thing.binding,
org.eclipse.smarthome.core.thing.binding.builder,
org.eclipse.smarthome.core.thing.type,
org.eclipse.smarthome.core.types,
org.openhab.binding.homie,
org.openhab.binding.homie.handler,
org.osgi.framework;version="1.8.0",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No versions

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

org.osgi.service.component;version="1.2.2",
org.slf4j
Service-Component: OSGI-INF/*.xml
Export-Package: org.openhab.binding.homie,
org.openhab.binding.homie.handler
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--

Copyright (c) 2014-2016 by the respective copyright holders.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems that this file has a missing or invalid copyright header, can you fix all of them by running

mvn license:format

Please commit only the ones for your binding.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.


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

-->
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" immediate="true" name="org.openhab.binding.homie.internal.HomieChannelTypeProviderImpl">

<implementation class="org.openhab.binding.homie.internal.HomieChannelTypeProviderImpl"/>
<service>
<provide interface="org.openhab.binding.homie.HomieChannelTypeProvider"/>
<provide interface="org.eclipse.smarthome.core.thing.type.ChannelTypeProvider"/>
</service>


</scr:component>
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--

Copyright (c) 2014-2016 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

-->
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" configuration-policy="require" immediate="true" name="binding.homie">

<implementation class="org.openhab.binding.homie.internal.HomieHandlerFactory"/>

<service>
<provide interface="org.eclipse.smarthome.core.thing.binding.ThingHandlerFactory"/>
</service>
<reference bind="setChannelProvider" cardinality="1..1" interface="org.openhab.binding.homie.HomieChannelTypeProvider" name="HomieChannelTypeProvider" policy="static" unbind="unsetChannelProvider"/>

</scr:component>
47 changes: 47 additions & 0 deletions addons/binding/org.openhab.binding.homie/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Homie Binding

This is the binding for devices that complie with the [Homie MQTT Convention]( https://github.com/marvinroger/homie).
This binding allows you to integrate all devices, as long as they complie with the specification.

## Naming definition

| Homie term | Eclipse Smart Home term |
| ---------- | ----------------------- |
| Device | Thing |
| Node | Channel |


## Discovery
Discovery is done by browsing the MQTT topics located below the basetopic defined in the binding configuration. So you have to make sure all your Homie devices communicate using the same basetopic.

## Additional convention

If you want openHAB to render your nodes properly, you have to provide the following topics.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a good idea. I've seen that you talked to the homie author already, but there is hopefully a way to solve it with the new 2.0 convention instead of adding something on top that only works for OH

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. Check homieiot/convention#12 (comment) for an ongoing discussion and add whatever might be missing

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To implement such a binding, it is essential to define additional conventions. There is no way to solve this without specifying additional stuff, or changing the convention itself. The later one is more of a long term process, that's why the binding uses the current convention and defines additional things.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought Homie 2.0 is not released yet and still being discussed

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is correct. My feeling is, that Marvin is currently preoccupied with other stuff. However the changes discussed in the issue are more or less settled and @Kwave 's PR goes a long way in making them final. homieiot/convention#27


| Property | Required | Message Format | Description | Example (Setable heater temperature) |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You would make me happy by formatting the tables in the MD file as well :-D

http://www.tablesgenerator.com/markdown_tables

Select 'File' > 'Past table data ...' and past the unformatted mark down table, you can then copy paste the formatted table 👍

|-|-|-|
| `$type` | Yes | `ESH:<category>` | Use one of the [Eclipse Smart Home channel categories](http://www.eclipse.org/smarthome/documentation/development/bindings/thing-definition.html#channel-categories) as node type. The type has to be prefixed with `ESH:`. | `ESH:Temperature` |
| `value` | Yes | arbitrary | The value of the node | `23.4`
| `itemtype` | Yes | `<itemtype>` | One of the item types valid for the category that you are using in the `$type` topic. (See the column 'Item Type' in the ESH channel categories table for valid values). | `Number` |
| `unit` | No | Any string | The unit of the value | `°C` |
| `min` | No | Any Number | Minimum value that `value` can contain | `25.0` |
| `max` | No | Any Number | Maximum value that `value` can contain | `31.0` |
| `step` | No | Any Number | Steps in which `value` may be increased or decreased | `0.5`|
| `desc` | No | Any String | Description for this node | `Heater in livingroom`


### Topic `value` (inbound)
The inbound messages (sent from a Homie device to the binding via the `value` topic) are automatically mapped to corresponding ESH command types, depending on the `itemtype` you have choosen. Auto mapping supports the following values:

| inbound message | ESH command type |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You would make me happy by formatting the tables in the MD file as well :-D

http://www.tablesgenerator.com/markdown_tables

Select 'File' > 'Past table data ...' and past the unformatted mark down table, you can then copy paste the formatted table 👍

|-|-|
|1, true| ON, OPEN |
|0, false| OFF, CLOSED |

Every other message will not be mapped to an ESH command, unless its value is a command type itself.

### Topic `value/set` (outbound)
The binding sends all commands to Homie devices as the string value that represents the command. So if you turn on a switch item in ESH, your homie device will receive the string `ON` at the topic `value/set`.

### Nodes that do not use the additional convention
All nodes that do not use the `ESH:` prefix in their `$type` topic will be made available as plain string items. They will be not writable, no matter if the `:settable` attribute is present or not.
Loading