Hm2mqtt NPM | npm.io

hm2mqtt.js

Node.js based Interface between Homematic and MQTT

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.

Installation

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, ...)

Command Line Options

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).

MQTT URL

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.

Topics

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 of hmip, rfd or hs485d.

Device and Channel Names

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",
    ...
}

ReGa (Homematic variables and programs)

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.

_NOTWORKING datapoints

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.

docker image for hm2mqtt.js

Usage (architecture: amd64)

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