Node.js based Interface between Homematic and MQTT
UNMAINTAINED - I gave up working on this project in favor of node-red-contrib-ccu respectively the CCU3/RaspberryMatic Addon RedMatic that includes node-red-contrib-ccu. The functionality of hm2mqtt.js will be implemented in node-red-contrib-ccu so this can act as a 1:1 drop-in-replacement.
Because hm2mqtt isn't developed anymore and I don't really like Java I decided to re-implement this with Node.js
It's kind of the same like the original hm2mqtt, but it supports BINRPC and XMLRPC (hm2mqtt only supports BINRPC), so it can be used with Homematic IP also. Furthermore it supports Rega variables and programs.
Prerequisites: Node.js 6.0 or higher.
npm install -g hm2mqtt
I suggest to use pm2 to manage the hm2mqtt process (start on system boot, manage log files, ...)
Use hm2mqtt --help
to get a list of available options. All options can also be set per environment variable (e.g.
setting HM2MQTT_VERBOSITY=debug
has the same effect as using --verbosity debug
as commandline parameter).
You can add Username/Password for the connection to the MQTT broker to the MQTT URL param like e.g.
mqtt://user:pass@broker
. For a secure connection via TLS use mqtts://
as URL scheme.
- Events are published on
<name>/status/<channelName>/<datapoint>
(JSON payload, follows mqtt-smarthome payload format) - Values can be set via
<name>/set/<channelAddress_or_channelName>/<datapoint>
(can be plain or JSON payload). Example:hmip/set/Light_Garage/STATE
, - Single values from arbitrary Paramsets can be set via
<name>/param/<channelAddress_or_channelName>/<paramset>/<datapoint>
. Example topic for setting the Mode of an 1st gen Thermostat HM-CC-TC:hm/param/Temperatur Hobbyraum Soll/MASTER/MODE_TEMPERATUR_REGULATOR
- Multiple values at once in arbitrary Paramsets can be set via
``<name>/param/<channelAddress_or_channelName>/<paramset>
. The payload has to be a JSON object like e.g.{"MODE_TEMPERATURE_REGULATOR":2,"TEMPERATUR_COMFORT_VALUE":24}
. - Arbitrary RPC methods can be called via
<name>/rpc/<iface>/<command>/<callId>
and respond to<name>/response/<callId>
(JSON encoded Array as payload). The callId can be an arbitrary string, its purpose is just to collate the response to the command. iface can be one ofhmip
,rfd
orhs485d
.
Device and Channel names are queried from ReGa, this can be disabled by setting the --disable-rega
option. To trigger
a re-read after changes on the ReGa you can publish a message to <name>/command/regasync
or just restart hm2mqtt.
As an alternative to using the names from ReGa you can also supply a json file with the --json-name-table
option
containing address to name mappings, created by e.g.
homematic-manager. This file should look like:
{
"EEQ1234567": "Device Name",
"EEQ1234567:1": "Channel Name",
...
}
To receive changes from ReGa you have to set --rega-poll-interval
and/or --rega-poll-trigger
.
--rega-poll-trigger
can be set to e.g. BidCoS-RF:50.PRESS_SHORT
, then a polling is done whenever this virtual button
is pressed. This is meant to create a "pseudo push mechanism" where a program on the ccu reacts on variable changes and
presses this virtual button.
Variables and Programs are published to <name>/status/<variableOrProgramName>
and can be set by sending a message to
<name>/rega/<variableOrProgramName>
. Publishing true
or false
to a program activates/deactivates the program. To
start a program publish the string start
.
hm2mqtt sends virtual datapoints named LEVEL_NOTWORKING
respectively STATE_NOTWORKING
for actuators that have a
WORKING
and/or DIRECTION
datapoint. The *_NOTWORKING
datapoints are only updated when WORKING
is false
- this
is useful for e.g. sliders in a UI to prevent jumping sliders when a Blind or Keymatic is moving or a Dimmer is dimming.
- pull the image to your machine, or if you are on a swarm to each node
docker pull mqttsmarthome/hm2mqtt:latest
- start the container with (e.g)
docker run -d -p 2126:2126 -p 2127:2127 --name hm2mqtt -e HM2MQTT_MQTT-URL="mqtt://xxx.xxx.xxx.xxx" -e HM2MQTT_MQTT-USERNAME="mqtt-user-name" -e HM2MQTT_MQTT-PASSWORD="mqtt-user-password" -e HM2MQTT_CCU-ADDRESS="xxx.xxx.xxx.xxx" -e HM2MQTT_INIT-ADDRESS="xxx.xxx.xxx.xxx" -e HM2MQTT_VERBOSITY="debug" mqttsmarthome/hm2mqtt
- or the service in your swarm with (e.g)
docker service create --name hm2mqtt \
--network ingress \
--publish 2126:2126 \
--publish 2127:2127 \
--env HM2MQTT_MQTT-URL="mqtt://xxx.xxx.xxx.xxx" \
--env HM2MQTT_CCU-ADDRESS="xxx.xxx.xxx.xxx" \
--env HM2MQTT_INIT-ADDRESS="xxx.xxx.xxx.xxx" \
--env HM2MQTT_VERBOSITY="debug" \
mqttsmarthome/hm2mqtt
- pull the image to your machine, or if you are on a swarm to each node
docker pull mqttsmarthome/hm2mqtt:armhf
- follow the description above (architecture: amd64), but leave out the pull sequence mentioned there.
MIT (c) 2017 Sebastian Raff