hm2mqtt 2.4.0 → 3.0.0

package/README.md

@@ -1,127 +1,222 @@
-# hm2mqtt.js
+# hm2mqtt
 
 [![mqtt-smarthome](https://img.shields.io/badge/mqtt-smarthome-blue.svg)](https://github.com/mqtt-smarthome/mqtt-smarthome)
 [![NPM version](https://badge.fury.io/js/hm2mqtt.svg)](http://badge.fury.io/js/hm2mqtt)
-[![Dependency Status](https://img.shields.io/gemnasium/hobbyquaker/hm2mqtt.js.svg?maxAge=2592000)](https://gemnasium.com/github.com/hobbyquaker/hm2mqtt.js)
-[![Build Status](https://travis-ci.org/hobbyquaker/hm2mqtt.js.svg?branch=master)](https://travis-ci.org/hobbyquaker/hm2mqtt.js)
-[![Coverage Status](https://coveralls.io/repos/github/hobbyquaker/hm2mqtt.js/badge.svg?branch=master)](https://coveralls.io/github/hobbyquaker/hm2mqtt.js?branch=master)
-[![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
-[![License][mit-badge]][mit-url]
+[![CI](https://github.com/hobbyquaker/hm2mqtt.js/actions/workflows/ci.yml/badge.svg)](https://github.com/hobbyquaker/hm2mqtt.js/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](LICENSE)
 
-> Node.js based Interface between Homematic and MQTT
+> Interface between the Homematic CCU and MQTT
 
-Because [hm2mqtt](https://github.com/owagner/hm2mqtt) isn't developed anymore and I don't really like Java I decided to 
-re-implement this with Node.js
+hm2mqtt connects a Homematic CCU (CCU2/CCU3/RaspberryMatic — BidCos-RF, BidCos-Wired, HmIP-RF,
+virtual devices/groups, CUxD, ReGaHSS variables and programs) to an MQTT broker following the
+[mqtt-smarthome](https://github.com/mqtt-smarthome/mqtt-smarthome) convention. Version 3 is an
+adapter on [mqtt-interfaces-core](https://github.com/hobbyquaker/mqtt-interfaces-core) and a
+drop-in replacement for the `ccu-mqtt` node of
+[node-red-contrib-ccu](https://github.com/rdmtc/node-red-contrib-ccu): same topics, same payloads.
 
-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.
+Contents: [Install](#install) · [Options](#options) · [Topics](#topics) · [Payloads](#payloads) ·
+[Names](#names) · [Home Assistant](#home-assistant) · [Migration](#migration) · [Development](#development)
 
+## Install
 
-### Installation
+Node.js ≥ 20.19. The host must be reachable from the CCU: the interface processes call back on
+`--xmlrpc-port` 2126 (and 2127 for binrpc/CUxD) — open them in the host firewall and, on a CCU
+with the firewall set to _restricted_, allow the host in the CCU's firewall settings.
 
-Prerequisites: [Node.js](https://nodejs.org) 6.0 or higher.
-
-`npm install -g hm2mqtt`
-
-I suggest to use [pm2](http://pm2.keymetrics.io/) 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).
-
-
-### Topics
+```
+npm install -g hm2mqtt
+hm2mqtt -a homematic-ccu3 -u mqtt://broker            # foreground
+sudo hm2mqtt --install -n hm -a homematic-ccu3 -u mqtt://broker   # systemd service hm2mqtt@hm
+```
 
-* Events are published on `<name>/status/<channelName>/<datapoint>` (JSON payload, follows 
-[mqtt-smarthome payload format](https://github.com/mqtt-smarthome/mqtt-smarthome/blob/master/Architecture.md))
-* 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`.
+`--install` writes the template unit `/etc/systemd/system/hm2mqtt@.service`, the instance
+config `/etc/hm2mqtt/hm.env` (every option as `HM2MQTT_*`) and uses `/var/lib/hm2mqtt/hm/` as
+state directory; broker credentials can live in the shared `/etc/mqtt-interfaces/broker.env`.
+`--uninstall -n hm` removes the instance. `--config-schema` prints a JSON schema of all options
+(management UIs like [she](https://github.com/hobbyquaker/she) build their config forms from it).
 
+Docker (build from the Dockerfile — no published image yet):
 
-### Device and Channel Names
+```
+docker build -t hm2mqtt .
+docker run -d --name hm2mqtt --network host -v hm2mqtt:/data \
+  -e HM2MQTT_CCU_ADDRESS=homematic-ccu3 -e HM2MQTT_MQTT_URL=mqtt://broker hm2mqtt
+```
 
-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](https://github.com/hobbyquaker/homematic-manager). This file should look like:
-```javascript
+Host networking, or publish 2126/2127 and set `HM2MQTT_INIT_ADDRESS` to the docker host's address
+so the CCU can call back. `--restart unless-stopped` brings it back after `maintenance/set/restart`.
+
+## Options
+
+`hm2mqtt --help` lists everything; every option is also an environment variable
+`HM2MQTT_<OPTION>` (e.g. `HM2MQTT_CCU_ADDRESS`), plus the unprefixed `MQTT_URL`, `MQTT_USERNAME`,
+`MQTT_PASSWORD`, `MQTT_TLS_CA` as fallback. Precedence: command line > environment > defaults.
+
+| option                                                                                                                                       | default                                           | description                                                                                                        |
+| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `-a, --ccu-address`                                                                                                                          | —                                                 | hostname or ip of the CCU (required)                                                                               |
+| `--ccu-tls`, `--ccu-insecure`, `--ccu-username`, `--ccu-password`                                                                            | off                                               | TLS ports (42001, 42010, …, ReGa 48181) and authentication of a CCU with the firewall/auth enabled                 |
+| `-i, --interfaces`                                                                                                                           | `BidCos-RF,HmIP-RF,VirtualDevices,BidCos-Wired`   | interfaces to subscribe to (`CUxD` opt-in), or `auto` to probe the ports                                           |
+| `--bidcos-binrpc`                                                                                                                            | off                                               | binrpc instead of xmlrpc for BidCos-RF/-Wired (CCU2, Homegear; a CCU3 proxies xmlrpc only)                         |
+| `-l, --listen-address`, `--init-address`, `--xmlrpc-port`, `--binrpc-port`                                                                   | first ipv4, =listen, 2126, 2127                   | callback servers the CCU pushes events to; `--init-address` when the CCU sees another address (NAT, Docker)        |
+| `--ping-timeout`                                                                                                                             | 60                                                | seconds without an event before a ping, twice that before a re-init (HmIP-RF uses 600)                             |
+| `--rega` / `--no-rega`                                                                                                                       | on                                                | names, rooms, functions, variables and programs from the ReGaHSS                                                   |
+| `--rega-poll-interval`, `--rega-poll-trigger`                                                                                                | 30, —                                             | variable/program poll interval (0 = off) and an optional `channel.datapoint` (virtual button) that triggers a poll |
+| `--ccu-timezone`                                                                                                                             | host                                              | IANA time zone of the CCU, for the timestamps of variables and cached values                                       |
+| `-m, --name-file`                                                                                                                            | —                                                 | JSON `{address: name}` overriding ReGa names ([example-names.json](example-names.json))                            |
+| `--item-template`, `--sysvar-item-template`, `--program-item-template`                                                                       | `${channelName\|channel}/${datapoint}`, `${name}` | how items (topic parts) are built, see [Item templates](#item-templates)                                           |
+| `--rega-names-interval`                                                                                                                      | 3600                                              | seconds between re-reads of names/rooms/functions (0 = only at start and on `set/rega/sync`)                       |
+| `--hm-payload` / `--no-hm-payload`                                                                                                           | on                                                | the `hm` meta data block in status payloads ([Payloads](#payloads))                                                |
+| `--plain-tree <level>`                                                                                                                       | —                                                 | additionally publish plain payloads under `<name>/<level>/…` (the second `ccu-mqtt` node of the Node-RED flow)     |
+| `--publish-cache`                                                                                                                            | off                                               | publish every datapoint value known to the ReGa at start (thousands of retained messages)                          |
+| `--publish-counters`, `--duty-cycle-interval`                                                                                                | on, 90                                            | rpc rx/tx counters and `listBidcosInterfaces` duty cycle polling (0 = off)                                         |
+| `--rpc-topics`                                                                                                                               | off                                               | arbitrary rpc calls via MQTT — an unrestricted API surface, only on a trusted broker                               |
+| `--state-dir`                                                                                                                                | `$STATE_DIRECTORY` or `~/.hm2mqtt`                | devices, paramset descriptions, names and last values                                                              |
+| `-u, --mqtt-url`, `--mqtt-username`, `--mqtt-password`, `--mqtt-tls-ca`, `-n, --name`, `--json-payloads`, `--maintenance`, `-v, --verbosity` | core                                              | shared options of every adapter; `--name` (default `hm`) is the topic prefix                                       |
+
+## Topics
+
+`<name>` = `--name` (default `hm`). Channel and variable names are the CCU's, verbatim (spaces,
+umlauts and `/` included; `+`, `#` and empty levels become `_`).
+
+| topic                                                                   | direction | payload                                                                                                            |
+| ----------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
+| `<name>/connected`                                                      | out       | `0` gone, `1` broker connected, `2` every interface subscribed and the ReGa answering (retained)                   |
+| `<name>/status/<channel>/<DATAPOINT>`                                   | out       | every event, retained except `PRESS_*` and other `ACTION` datapoints                                               |
+| `<name>/status/<channel>/LEVEL_NOTWORKING`, `…/STATE_NOTWORKING`        | out       | the value of an actuator once it stopped moving/dimming (for UI sliders)                                           |
+| `<name>/status/<variable>`, `<name>/status/<program>`                   | out       | variables and programs (`val` = value / active), on change and at start                                            |
+| `<name>/status/interface/<interface>/connected`                         | out       | `true`/`false` per interface process                                                                               |
+| `<name>/status/counter/<interface>/rx`, `…/tx`                          | out       | received event batches / sent setValue+putParamset calls since start                                               |
+| `<name>/status/<interfaceAddress>/DUTY_CYCLE`                           | out       | duty cycle of every RF adapter (`listBidcosInterfaces`), plus `CARRIER_SENSE_LEVEL` and `CONNECTED` where reported |
+| `<name>/info`                                                           | out       | adapter, version, `ccu`, `interfaces`, `devices` (retained)                                                        |
+| `<name>/set/<channelNameOrAddress>/<DATAPOINT>`                         | in        | plain value or `{"val": …}`; cast by the paramset description (booleans, `ENUM` names, floats)                     |
+| `<name>/set/<variable>`                                                 | in        | value; `ENUM` names accepted                                                                                       |
+| `<name>/set/<program>`                                                  | in        | `true`/`false` activates/deactivates, anything else (e.g. `start`) executes the program                            |
+| `<name>/set/rega/sync`                                                  | in        | re-read names, rooms and functions after changes on the CCU                                                        |
+| `<name>/paramset/<channelOrDevice>/<PARAMSET>`                          | in        | JSON object → `putParamset`, e.g. `{"MODE_TEMPERATUR_REGULATOR": 2}` on `MASTER`                                   |
+| `<name>/paramset/<channelOrDevice>/<PARAMSET>/<PARAM>`                  | in        | single value → `putParamset`                                                                                       |
+| `<name>/rpc/<interface>/<method>/<callId>` → `<name>/response/<callId>` | in/out    | `--rpc-topics` only: JSON array of parameters, answer as JSON (or `{"error": …}`)                                  |
+| `<name>/maintenance/set/loglevel`, `…/restart`                          | in        | `error`/`warn`/`info`/`debug`; graceful restart (core, `--no-maintenance` disables)                                |
+
+### Item templates
+
+The part after `status/` and `set/` (the _item_) is rendered from a template with the fields of the
+`hm` block as placeholders, like node-red-contrib-ccu's topic templates — `--item-template`
+(default `${channelName|channel}/${datapoint}`), `--sysvar-item-template` and
+`--program-item-template` (default `${name}`). `|` is a fallback chain, field names are
+case-insensitive, an empty result becomes `_`. Examples: `${device}/${channelIndex}/${datapoint}`
+(addresses only), `${room|_}/${channelName}/${datapoint}`, `${iface}/${channel}/${datapoint}`,
+`sysvar/${name}`. `set` topics are resolved through a reverse index of every known channel and
+datapoint (the address form `<address>/<DATAPOINT>` always works too); channels rendering the same
+item are listed at start, the first one wins.
+
+Use the channel name (`Licht Küche`) or the address (`OEQ1234567:1`) in `set` and `paramset`
+topics. `set/<channel>/<DATAPOINT>` with two channels sharing a name reaches the first one — the
+start-up log lists duplicate names.
+
+## Payloads
+
+Status payloads are JSON: `{"val": …, "ts": <ms>, "lc": <ms>, "hm": {…}}` — `val` the value,
+`ts` the time of the event (variables: the CCU's timestamp), `lc` the last change. `hm` is the
+meta data block of node-red-contrib-ccu's messages, field for field:
+
+```json
 {
-    "EEQ1234567": "Device Name",
-    "EEQ1234567:1": "Channel Name",
-    ...
+  "val": 0.5,
+  "ts": 1787900000000,
+  "lc": 1787899000000,
+  "hm": {
+    "ccu": "homematic-ccu3",
+    "iface": "BidCos-RF",
+    "device": "OEQ1234567",
+    "deviceName": "Dimmer Flur",
+    "deviceType": "HM-LC-Dim1L-CV",
+    "channel": "OEQ1234567:1",
+    "channelName": "Licht Flur",
+    "channelType": "DIMMER",
+    "channelIndex": 1,
+    "datapoint": "LEVEL",
+    "datapointName": "BidCos-RF.OEQ1234567:1.LEVEL",
+    "datapointType": "FLOAT",
+    "datapointMin": 0,
+    "datapointMax": 1,
+    "datapointDefault": 0,
+    "datapointControl": "DIMMER.LEVEL",
+    "datapointUnit": "100%",
+    "valuePrevious": 0.3,
+    "valueStable": 0.5,
+    "rooms": ["Flur"],
+    "room": "Flur",
+    "functions": ["Licht"],
+    "function": "Licht",
+    "ts": 1787900000000,
+    "tsPrevious": 1787899000000,
+    "lc": 1787899000000,
+    "change": true,
+    "cache": false,
+    "uncertain": false,
+    "working": false,
+    "direction": 0,
+    "stable": true
+  }
 }
 ```
 
+`ENUM` datapoints carry `datapointEnum` (the value list) and `valueEnum` (the name of the current
+value). Variables have `type: "SYSVAR"` with `valueType`, `unit`, `enum`, `valueEnum`, `id` and —
+when bound to a channel — the channel fields; programs `type: "PROGRAM"` with `active`,
+`activePrevious`, `ts` (last execution). `--no-hm-payload` leaves `{val, ts, lc}`,
+`--no-json-payloads` publishes the bare value. `--plain-tree state` mirrors every item to
+`<name>/state/…` with plain values and booleans as `0`/`1`.
 
-### ReGa (Homematic variables and programs)
+## Names
 
-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.
+Names come from the ReGa (devices, channels, rooms, functions), are cached in the state
+directory and re-read with `<name>/set/rega/sync`. A `--name-file` overrides single addresses.
+Without the ReGa (`--no-rega`) topics use addresses. Events of channels without a name use the
+address as well.
 
-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`.
+## Home Assistant
 
+The core's discovery options (`--ha-discovery`, `--ha-prefix`) exist, but 3.0 does not announce
+devices yet — channel-type to entity mapping is planned for 3.1 (ROADMAP §10).
 
-### _NOTWORKING datapoints
+## Migration
 
-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.
+### From the node-red-contrib-ccu `ccu-mqtt` flow
 
+Same topics for events, variables, programs, counters, `set` and `paramset`. Differences:
 
-## docker image for hm2mqtt.js
+- `<name>/connected` reflects the CCU: `1` while an interface is down (the flow always said `2`).
+- `hm.ccu` is the configured `--ccu-address` (the flow, running on the CCU, said `localhost`).
+- Counters and duty cycle payloads are `{val, ts, lc}` like every other status (`val` unchanged).
+- `PRESS_*` **and** other `ACTION` datapoints are not retained.
+- Variables and programs are published at start too, not only on change; polling is on by default.
+- `hm` carries `datapointEnum`/`valueEnum` (from the `VALUE_LIST`) and `datapointUnit`.
+- `paramset` values are cast by their own description and rejected when not writeable.
+- The second (plain) `ccu-mqtt` node is `--plain-tree state`; the `rpc` topic of the node never
+  worked — `--rpc-topics` brings the 2.x form back.
 
-#### 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_MQTT-USERNAME="mqtt-user-name" \
---env HM2MQTT_MQTT-PASSWORD="mqtt-user-password" \
---env HM2MQTT_CCU-ADDRESS="xxx.xxx.xxx.xxx" \
---env HM2MQTT_INIT-ADDRESS="xxx.xxx.xxx.xxx" \
---env HM2MQTT_VERBOSITY="debug" \
-mqttsmarthome/hm2mqtt
-```
+### From hm2mqtt 2.x
 
-#### Usage (architecture: armhf)
-- 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.
+| 2.x                                                                  | 3.0                                                                               |
+| -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `hm/status/<ch>/<dp>` with `hm: {ADDRESS, UNIT, ENUM}`               | same topic, `hm` block as above (`channel`, `datapointUnit`, `valueEnum`)         |
+| `hm/rega/<variable\|program>`                                        | `hm/set/<variable\|program>`                                                      |
+| `hm/param/<ch>/<paramset>/<dp>`                                      | `hm/paramset/<ch>/<paramset>/<param>`                                             |
+| `hm/rpc/<rfd\|hmip\|hs485d>/<method>/<callid>`                       | `hm/rpc/<BidCos-RF\|HmIP-RF\|BidCos-Wired\|…>/<method>/<callid>` (`--rpc-topics`) |
+| `hm/command/regasync`                                                | `hm/set/rega/sync`                                                                |
+| `hm/status/counter/<rfd\|hmip>/rpc/<rx\|tx>`                         | `hm/status/counter/<BidCos-RF\|HmIP-RF>/<rx\|tx>`                                 |
+| `db/extend/hm/<address>` (`--publish-metadata`)                      | dropped                                                                           |
+| `--insecure`, `--disable-rega`, `--json-name-table`, `--mqtt-retain` | `--ccu-insecure` / `--mqtt-tls-ca`, `--no-rega`, `--name-file`, —                 |
+| interface names `rfd`, `hmip`, `hs485d`                              | `BidCos-RF`, `HmIP-RF`, `BidCos-Wired`                                            |
 
+## Development
 
-## License
+`npm test` (node:test, no CCU needed), `npm run lint`. `deploy.sh` ships the package (and
+`file:../` siblings) to a host and restarts the `hm2mqtt@*` units. Plan and decisions:
+[ROADMAP.md](ROADMAP.md); changes: [CHANGELOG.md](CHANGELOG.md).
 
-MIT (c) 2017 [Sebastian Raff](https://github.com/hobbyquaker)
+## License
 
-[mit-badge]: https://img.shields.io/badge/License-MIT-blue.svg?style=flat
-[mit-url]: LICENSE
+MIT (c) Sebastian Raff

package/config.js

@@ -1,59 +1,113 @@
-const pkg = require('./package.json');
+import {parseConfig} from 'mqtt-interfaces-core';
+import pkg from './package.json' with {type: 'json'};
+import {DEFAULT_INTERFACES, INTERFACE_NAMES} from './lib/interfaces.js';
+import {DEFAULT_ITEM_TEMPLATE, DEFAULT_SYSVAR_ITEM_TEMPLATE, DEFAULT_PROGRAM_ITEM_TEMPLATE} from './lib/topics.js';
 
-module.exports = require('yargs')
-    .env('HM2MQTT')
-    .usage(pkg.name + ' ' + pkg.version + '\n' + pkg.description + '\n\nUsage: $0 [options]')
-    .describe('verbosity', 'possible values: "error", "warn", "info", "debug"')
-    .describe('name', 'instance name. used as mqtt client id and as prefix for connected topic')
-    .describe('mqtt-url', 'mqtt broker url. See https://github.com/mqttjs/MQTT.js#connect-using-a-url')
-    .describe('mqtt-username', 'mqtt broker username')
-    .describe('mqtt-password', 'mqtt broker password')
-    .describe('ping-interval', 'Send a Ping if no event occured in the last interval. Re-Init on next interval')
-    .describe('disable-rega', 'Don\'t sync names from ReGa')
-    .describe('json-name-table', 'A JSON file that maps device and channel addresses to names')
-    .describe('rega-poll-interval', 'Interval in seconds to poll variables from Rega. Set to 0 to disable polling')
-    .describe('rega-poll-trigger', 'A virtual button that triggers a variable poll. Example: BidCoS-RF:50.PRESS_SHORT')
-    .describe('listen-address', 'Address the RPC servers bind to')
-    .describe('init-address', 'Address used in the RPC init. Normally there is no need to set this')
-    .describe('help', 'show help')
-    .describe('publish-metadata', '')
-    .describe('mqtt-retain', 'enable/disable retain flag for mqtt messages')
-    .alias({
-        a: 'ccu-address',
-        b: 'binrpc-listen-port',
-        d: 'disable-rega',
-        h: 'help',
-        i: 'ping-interval',
-        j: 'json-name-table',
-        l: 'listen-port',
-        m: 'mqtt-url',
-        n: 'name',
-        p: 'mqtt-password',
-        q: 'hmip-reconnect-interval',
-        r: 'listen-address',
-        s: 'init-address',
-        u: 'mqtt-username',
-        v: 'verbosity'
-    })
-    .boolean('mqtt-retain')
-    .default({
-        'disable-rega': false,
-        'mqtt-url': 'mqtt://127.0.0.1',
-        name: 'hm',
-        verbosity: 'info',
-        'listen-address': require('./firstip.js'),
-        'listen-port': 2126,
-        'binrpc-listen-port': 2127,
-        'ping-interval': 30,
-        'hmip-reconnect-interval': 600,
-        'rega-poll-interval': 0,
-        'rega-poll-trigger': '',
-        'publish-metadata': false,
-        'mqtt-retain': true
-    })
-    .demandOption([
-        'ccu-address'
-    ])
-    .version()
-    .help('help')
-    .argv;
+export const OPTIONS = {
+    'ccu-address': {alias: 'a', type: 'string', describe: 'hostname or ip of the CCU', demandOption: true},
+    'ccu-tls': {type: 'boolean', describe: 'use the TLS ports (4xxxx) and https for ReGa', default: false},
+    'ccu-insecure': {type: 'boolean', describe: "accept the CCU's self-signed certificate", default: false},
+    'ccu-username': {type: 'string', describe: 'CCU user (authentication enabled on the CCU)'},
+    'ccu-password': {type: 'string', describe: 'CCU password', secret: true},
+    interfaces: {
+        alias: 'i',
+        type: 'string',
+        describe: `comma separated interfaces (${INTERFACE_NAMES.join(', ')}) or "auto" (probe the ports)`,
+        default: DEFAULT_INTERFACES.join(','),
+    },
+    'bidcos-binrpc': {
+        type: 'boolean',
+        describe: 'talk binrpc instead of xmlrpc to BidCos-RF and BidCos-Wired',
+        default: false,
+    },
+    'listen-address': {
+        alias: 'l',
+        type: 'string',
+        describe: 'address the rpc callback servers bind to (default: first non-loopback ipv4)',
+    },
+    'init-address': {
+        type: 'string',
+        describe: 'address the CCU calls back (default: listen address); needed behind NAT/Docker',
+    },
+    'xmlrpc-port': {type: 'number', describe: 'xmlrpc callback server port', default: 2126},
+    'binrpc-port': {type: 'number', describe: 'binrpc callback server port', default: 2127},
+    'ping-timeout': {
+        type: 'number',
+        describe: 'seconds without an event before ping / re-init (HmIP-RF: 600)',
+        default: 60,
+    },
+    rega: {
+        type: 'boolean',
+        describe: 'names, rooms, functions, variables and programs from ReGa (--no-rega: addresses only)',
+        default: true,
+    },
+    'rega-poll-interval': {type: 'number', describe: 'seconds between variable/program polls, 0 = off', default: 30},
+    'rega-names-interval': {
+        type: 'number',
+        describe:
+            'seconds between re-reads of names, rooms and functions from ReGa, 0 = only at start and on set/rega/sync',
+        default: 3600,
+    },
+    'rega-poll-trigger': {
+        type: 'string',
+        describe: 'channel.datapoint whose event triggers a variable/program poll, e.g. BidCoS-RF:50.PRESS_SHORT',
+    },
+    'ccu-timezone': {type: 'string', describe: "IANA time zone of the CCU (default: this host's time zone)"},
+    'name-file': {
+        alias: 'm',
+        type: 'string',
+        describe: 'JSON file {address: name} overriding the ReGa names (see example-names.json)',
+        file: {
+            format: 'json',
+            example: 'example-names.json',
+            schema: 'names.schema.json',
+            describe: 'device and channel names',
+        },
+    },
+    'item-template': {
+        type: 'string',
+        describe:
+            'item (topic part after status/ and set/) of a datapoint; ${field} placeholders with | fallbacks, every hm field',
+        default: DEFAULT_ITEM_TEMPLATE,
+    },
+    'sysvar-item-template': {
+        type: 'string',
+        describe: 'item of a system variable',
+        default: DEFAULT_SYSVAR_ITEM_TEMPLATE,
+    },
+    'program-item-template': {type: 'string', describe: 'item of a program', default: DEFAULT_PROGRAM_ITEM_TEMPLATE},
+    'hm-payload': {type: 'boolean', describe: 'add the "hm" meta data block to every status payload', default: true},
+    'plain-tree': {
+        type: 'string',
+        describe: 'additionally publish plain payloads under <name>/<level>/... (e.g. "state")',
+    },
+    'publish-cache': {type: 'boolean', describe: 'publish every datapoint value from ReGa at start', default: false},
+    'publish-counters': {
+        type: 'boolean',
+        describe: 'publish rpc rx/tx counters on counter/<interface>/rx|tx',
+        default: true,
+    },
+    'duty-cycle-interval': {type: 'number', describe: 'seconds between duty cycle polls, 0 = off', default: 90},
+    'rpc-topics': {
+        type: 'boolean',
+        describe: 'accept arbitrary rpc calls on <name>/rpc/<interface>/<method>/<callid> (security surface!)',
+        default: false,
+    },
+    'state-dir': {
+        type: 'string',
+        describe:
+            'directory for devices, paramset descriptions, names and last values (default: $STATE_DIRECTORY or ~/.hm2mqtt)',
+        default: process.env.STATE_DIRECTORY,
+    },
+};
+
+export default parseConfig({
+    pkg,
+    options: OPTIONS,
+    defaults: {name: 'hm'},
+    examples: [
+        ['$0 -a homematic-ccu3 -u mqtt://broker', 'run in the foreground'],
+        ['$0 -a 192.168.1.50 -i BidCos-RF,HmIP-RF --plain-tree state', 'two interfaces plus the plain mirror tree'],
+        ['sudo $0 --install -n hm -a homematic-ccu3 -u mqtt://broker', 'install as service hm2mqtt@hm'],
+    ],
+});

package/example-names.json

@@ -0,0 +1,6 @@
+{
+  "OEQ1234567": "Steckdose Wohnzimmer",
+  "OEQ1234567:1": "Steckdose Wohnzimmer",
+  "000A1B2C3D4E5F": "Heizung Bad",
+  "000A1B2C3D4E5F:1": "Heizung Bad"
+}