<commit_before>hm2mqtt
=======

  Written and (C) 2015 <NAME> <<EMAIL>> 
  
  Provided under the terms of the MIT license.


Overview
--------
hm2mqtt is a gateway between a Homematic home automation system and MQTT. 

It is intended as a building block in heterogenous smart home environments where 
an MQTT message broker is used as the centralized message bus.
See https://github.com/mqtt-smarthome for a rationale and architectural overview.

hm2mqtt communicates with Homematic using the documented XML-RPC API
and thus requires either an CCU1/CCU2 or a Homematic configuration adapter with
the XML-RPC service running on a host (currently Windows-only). It is _not_
able to talk directly to Homematic devices using 3rd party hardware like a CUL.


Dependencies
------------
* Java 1.7 (or higher) SE Runtime Environment: https://www.java.com/
* Eclipse Paho: https://www.eclipse.org/paho/clients/java/ (used for MQTT communication)
* Minimal-JSON: https://github.com/ralfstx/minimal-json (used for JSON creation and parsing)

It is possible to run hm2mqtt directly on a CCU2, using the Embedded JRE. Courtesy of hobbyquaker,
a CCU2 addon wrapper is available.

[![Build Status](https://travis-ci.org/owagner/hm2mqtt.png)](https://travis-ci.org/owagner/hm2mqtt)
Automatically built jars (and the CCU2 addon) can be downloaded from the release page on GitHub at 
https://github.com/owagner/hm2mqtt/releases


Device names and topic structure
--------------------------------
hm2mqtt will try to read device and channel names from the specified HM hosts using the ReGa TCL interface
on port 8181. If this succeeds, channel names will be resolved into symbolic names before publishing.

The topics generated and accepted are of the form

`prefix/function/channel/datapoint`

The *function* is _status_ for published status reports, _set_ for inbound change requests
or _get_ to synchronously and activly request a value from a device.

The *channel* is either the raw address or a name resolved by querying the ReGa.

Note that incoming messages are accepted on both the symbolic and the address channel name.

A special topic is *prefix/connected*. It holds an enum value which denotes whether the adapter is
currently running (1) and connected to HM (2). It's set to 0 on disconnect using a MQTT will.


Homematic Data types
--------------------
Homematic datapoints can have a variety of data types:

* FLOAT
* INTEGER
* BOOL
* ENUM
* STRING
* ACTION

hm2mqtt needs to know the type of a data point in order to properly encode the outgoing messages.
Types are obtained using *getParamsetDescription* calls when new devices show up, and are cached
in the device cache file.


Registering as a link partner
-----------------------------
hm2mqtt will report to the Homematic interface server (e.g. the CCU) that it is explicitely using 
each and every datapoint.  This will in turn cause the interface server to register itself as a
link partner with the remote device.

This means that everytime the remote device sends a status message, it expects the interface
server to acknowledge this (true bidirectional communication), like it does with any other direct
link partners.

If the interface server is not linked with the device, it will still receive and process
status messages. However, there is no bidirectional communication in that case -- if the interface
server does, for any reason (like RF interference), not receive a status message, the remote
device will not resend it. This particular behavior is often not well understood.

One side-effect of this is that on the first time that hm2mqtt is started, there may be a
lot of new pending configs in case devices were not previously linked with the interface
server. For a CCU, this is for example the case if a device is not used in a ReGa program.


MQTT Message format
--------------------
The message format generated is a JSON encoded object with the following members:

* val - the actual value, in numeric format
* hm_addr - source HM device address and channel number
* hm_getid - will be set in responses to get requests and contains the payload from the
             get message
* hm_unit - has the unit specifier from the ParamsetDescription of the datapoint
* hm_enum - has the textual enum value from the ParamsetDescription of the datapoint, for ENUM types

Datapoints with type _ACTION_ are sent with the MQTT retain  flag set to _false_, all others with retain set to _true_.
_ACTION_s e.G. are press reports (PRESS_SHORT, PRESS_LONG, PRESS_CONT)


Usage
-----

Configuration options can either be specified on the command line, or as system properties with the prefix "hm2mqtt".
Examples:

    java -jar hm2mqtt.jar hm.ip=192.168.0.10
    
    java -Dhm.hm.ip=192.168.0.10 -jar hm2mqtt.jar
    
### Available options:    

- mqtt.server

  ServerURI of the MQTT broker to connect to. Defaults to "tcp://localhost:1883". 
  
  Two types of connection are supported: tcp:// for a TCP connection and ssl:// for a TCP connection secured by SSL/TLS. 
  For example:<commit_msg>Fix example cmdline: hm.ip -> hm.host<commit_after>hm2mqtt
=======

  Written and (C) 2015 <NAME> <<EMAIL>> 
  
  Provided under the terms of the MIT license.


Overview
--------
hm2mqtt is a gateway between a Homematic home automation system and MQTT. 

It is intended as a building block in heterogenous smart home environments where 
an MQTT message broker is used as the centralized message bus.
See https://github.com/mqtt-smarthome for a rationale and architectural overview.

hm2mqtt communicates with Homematic using the documented XML-RPC API
and thus requires either an CCU1/CCU2 or a Homematic configuration adapter with
the XML-RPC service running on a host (currently Windows-only). It is _not_
able to talk directly to Homematic devices using 3rd party hardware like a CUL.


Dependencies
------------
* Java 1.7 (or higher) SE Runtime Environment: https://www.java.com/
* Eclipse Paho: https://www.eclipse.org/paho/clients/java/ (used for MQTT communication)
* Minimal-JSON: https://github.com/ralfstx/minimal-json (used for JSON creation and parsing)

It is possible to run hm2mqtt directly on a CCU2, using the Embedded JRE. Courtesy of hobbyquaker,
a CCU2 addon wrapper is available.

[![Build Status](https://travis-ci.org/owagner/hm2mqtt.png)](https://travis-ci.org/owagner/hm2mqtt)
Automatically built jars (and the CCU2 addon) can be downloaded from the release page on GitHub at 
https://github.com/owagner/hm2mqtt/releases


Device names and topic structure
--------------------------------
hm2mqtt will try to read device and channel names from the specified HM hosts using the ReGa TCL interface
on port 8181. If this succeeds, channel names will be resolved into symbolic names before publishing.

The topics generated and accepted are of the form

`prefix/function/channel/datapoint`

The *function* is _status_ for published status reports, _set_ for inbound change requests
or _get_ to synchronously and activly request a value from a device.

The *channel* is either the raw address or a name resolved by querying the ReGa.

Note that incoming messages are accepted on both the symbolic and the address channel name.

A special topic is *prefix/connected*. It holds an enum value which denotes whether the adapter is
currently running (1) and connected to HM (2). It's set to 0 on disconnect using a MQTT will.


Homematic Data types
--------------------
Homematic datapoints can have a variety of data types:

* FLOAT
* INTEGER
* BOOL
* ENUM
* STRING
* ACTION

hm2mqtt needs to know the type of a data point in order to properly encode the outgoing messages.
Types are obtained using *getParamsetDescription* calls when new devices show up, and are cached
in the device cache file.


Registering as a link partner
-----------------------------
hm2mqtt will report to the Homematic interface server (e.g. the CCU) that it is explicitely using 
each and every datapoint.  This will in turn cause the interface server to register itself as a
link partner with the remote device.

This means that everytime the remote device sends a status message, it expects the interface
server to acknowledge this (true bidirectional communication), like it does with any other direct
link partners.

If the interface server is not linked with the device, it will still receive and process
status messages. However, there is no bidirectional communication in that case -- if the interface
server does, for any reason (like RF interference), not receive a status message, the remote
device will not resend it. This particular behavior is often not well understood.

One side-effect of this is that on the first time that hm2mqtt is started, there may be a
lot of new pending configs in case devices were not previously linked with the interface
server. For a CCU, this is for example the case if a device is not used in a ReGa program.


MQTT Message format
--------------------
The message format generated is a JSON encoded object with the following members:

* val - the actual value, in numeric format
* hm_addr - source HM device address and channel number
* hm_getid - will be set in responses to get requests and contains the payload from the
             get message
* hm_unit - has the unit specifier from the ParamsetDescription of the datapoint
* hm_enum - has the textual enum value from the ParamsetDescription of the datapoint, for ENUM types

Datapoints with type _ACTION_ are sent with the MQTT retain  flag set to _false_, all others with retain set to _true_.
_ACTION_s e.G. are press reports (PRESS_SHORT, PRESS_LONG, PRESS_CONT)


Usage
-----

Configuration options can either be specified on the command line, or as system properties with the prefix "hm2mqtt".
Examples:

    java -jar hm2mqtt.jar hm.host=192.168.0.10
    
    java -Dhm.hm.host=192.168.0.10 -jar hm2mqtt.jar
    
### Available options:    

- mqtt.server

  ServerURI of the MQTT broker to connect to. Defaults to "tcp://localhost:1883". 
  
  Two types of connection are supported: tcp:// for a TCP connection and ssl:// for a TCP connection secured by SSL/TLS. 
  For example:
{'fraction_non_alphanumeric': 0.07312018946121966, 'fraction_numerical': 0.01085454904282613, 'mean_word_length': 3.625741670470105, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 10, 'https://': 14, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1932382', 'n_tokens_mistral': 2834, 'n_tokens_neox': 2673, 'n_words': 1445}