hm2mqtt 3.4.6 → 3.5.0

package/README.md

@@ -164,21 +164,39 @@ umlauts and `/` included; `+`, `#` and empty levels become `_`).
 | `<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.
+### Topic templates
+
+Every topic is a template, whole. `${prefix}` is the instance name (`--name`, default `hm`), the
+other placeholders are the fields of the `hm` block:
+
+| Option                   | Default                                                 |
+| ------------------------ | ------------------------------------------------------- |
+| `--topic-status`         | `${prefix}/status/${channelName\|channel}/${datapoint}` |
+| `--topic-set`            | `${prefix}/set/${channelName\|channel}/${datapoint}`    |
+| `--topic-sysvar-status`  | `${prefix}/status/${name}`                              |
+| `--topic-sysvar-set`     | `${prefix}/set/${name}`                                 |
+| `--topic-program-status` | `${prefix}/status/${name}`                              |
+| `--topic-program-set`    | `${prefix}/set/${name}`                                 |
+
+The defaults render exactly the topics hm2mqtt has always used, so nothing moves unless you move it.
+`|` is a fallback chain, field names are case-insensitive, an empty result becomes `_`. Examples:
+`${prefix}/${room|_}/${channelName}/${datapoint}`, `smarthome/${iface}/${channel}/${datapoint}`,
+`${prefix}/status/${device}/${channelIndex}/${datapoint}`.
+
+What hm2mqtt subscribes follows from the literal part of the `set` templates: everything up to the
+first placeholder, plus `#` — `hm/set/#` for the default. A rendered level may contain slashes (a
+channel named `Haus/OG/Licht` is legitimate), so incoming topics are resolved by looking up the
+whole topic in an index of every known channel and datapoint, not by counting levels. Below the
+literal part the address form still works (`hm/set/OEQ1234567:1/STATE`), as do the commands
+(`hm/set/rega/sync`). Channels rendering the same topic are listed at start; the first one wins.
+
+Moving the templates moves the topics for everything subscribed to them, and Home Assistant
+discovery re-announces every entity, because the state and command topics it publishes come from
+these same templates.
+
+`--item-template`, `--sysvar-item-template` and `--program-item-template` named only the part after
+`<name>/status/`. They still work — each becomes the matching pair of topic templates — but the
+topic options replace them.
 
 ## Payloads
 

package/config.js

@@ -2,7 +2,15 @@ import {parseConfig} from 'mqtt-interfaces-core';
 import pkg from './package.json' with {type: 'json'};
 import {DEFAULT_INTERFACES, INTERFACE_NAMES} from './lib/interfaces.js';
 import {discoveryHint} from './lib/discovery.js';
-import {DEFAULT_ITEM_TEMPLATE, DEFAULT_SYSVAR_ITEM_TEMPLATE, DEFAULT_PROGRAM_ITEM_TEMPLATE} from './lib/topics.js';
+import {
+    applyItemTemplates,
+    DEFAULT_TOPIC_STATUS,
+    DEFAULT_TOPIC_SET,
+    DEFAULT_TOPIC_SYSVAR_STATUS,
+    DEFAULT_TOPIC_SYSVAR_SET,
+    DEFAULT_TOPIC_PROGRAM_STATUS,
+    DEFAULT_TOPIC_PROGRAM_SET,
+} from './lib/topics.js';
 
 export const OPTIONS = {
     'ccu-address': {
@@ -76,18 +84,43 @@ export const OPTIONS = {
             describe: 'device and channel names',
         },
     },
-    'item-template': {
+    'topic-status': {
         type: 'string',
         describe:
-            'item (topic part after status/ and set/) of a datapoint; ${field} placeholders with | fallbacks, every hm field',
-        default: DEFAULT_ITEM_TEMPLATE,
+            'status topic of a datapoint - the whole topic; ${field} placeholders with | fallbacks, ${prefix} is the instance name',
+        default: DEFAULT_TOPIC_STATUS,
+    },
+    'topic-set': {
+        type: 'string',
+        describe: 'topic a datapoint is written on; what is subscribed follows from its literal part',
+        default: DEFAULT_TOPIC_SET,
+    },
+    'topic-sysvar-status': {
+        type: 'string',
+        describe: 'status topic of a system variable',
+        default: DEFAULT_TOPIC_SYSVAR_STATUS,
+    },
+    'topic-sysvar-set': {
+        type: 'string',
+        describe: 'topic a system variable is written on',
+        default: DEFAULT_TOPIC_SYSVAR_SET,
+    },
+    'topic-program-status': {
+        type: 'string',
+        describe: 'status topic of a program',
+        default: DEFAULT_TOPIC_PROGRAM_STATUS,
     },
-    'sysvar-item-template': {
+    'topic-program-set': {
+        type: 'string',
+        describe: 'topic a program is started on',
+        default: DEFAULT_TOPIC_PROGRAM_SET,
+    },
+    'item-template': {
         type: 'string',
-        describe: 'item of a system variable',
-        default: DEFAULT_SYSVAR_ITEM_TEMPLATE,
+        describe: 'deprecated, use --topic-status/--topic-set: item part of the classic topics',
     },
-    'program-item-template': {type: 'string', describe: 'item of a program', default: DEFAULT_PROGRAM_ITEM_TEMPLATE},
+    'sysvar-item-template': {type: 'string', describe: 'deprecated, use --topic-sysvar-status/-set'},
+    'program-item-template': {type: 'string', describe: 'deprecated, use --topic-program-status/-set'},
     payload: {
         type: 'string',
         describe:
@@ -130,15 +163,17 @@ export const OPTIONS = {
     },
 };
 
-export default parseConfig({
-    pkg,
-    options: OPTIONS,
-    defaults: {name: 'hm'},
-    discovery: discoveryHint(),
-    examples: [
-        ['$0 --discover', 'find CCUs on the network and exit'],
-        ['$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'],
-    ],
-});
+export default applyItemTemplates(
+    parseConfig({
+        pkg,
+        options: OPTIONS,
+        defaults: {name: 'hm'},
+        discovery: discoveryHint(),
+        examples: [
+            ['$0 --discover', 'find CCUs on the network and exit'],
+            ['$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/index.js

@@ -10,7 +10,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {createAdapter, createLogger, runDiscovery, autoAddress} from 'mqtt-interfaces-core';
+import {createAdapter, createLogger, runDiscovery, autoAddress, StatusTracker} from 'mqtt-interfaces-core';
 import {Rega} from 'homematic-rega';
 import config from './config.js';
 import pkg from './package.json' with {type: 'json'};
@@ -21,7 +21,16 @@ import {Metadata} from './lib/metadata.js';
 import {ValueStore, hmBlock, isEvent} from './lib/values.js';
 import {RegaSync} from './lib/rega.js';
 import {castValue, isWriteable} from './lib/cast.js';
-import {sanitizeName, resolveSet, resolveParamset, plainValue, compileTemplate, ItemIndex} from './lib/topics.js';
+import {
+    sanitizeName,
+    resolveSet,
+    resolveParamset,
+    plainValue,
+    compileTemplate,
+    subscribePattern,
+    templateRemainder,
+    ItemIndex,
+} from './lib/topics.js';
 import {compileIgnore} from './lib/roles.js';
 import {discoveryModel} from './lib/hadiscovery.js';
 import {discoveryHint} from './lib/discovery.js';
@@ -128,6 +137,23 @@ const outValue = (value) => (payloadFormat === 'plain' ? plainValue(value) : val
 
 const ignored = compileIgnore(config.ignore);
 
+/*
+ * Topics are rendered from templates, whole. `${prefix}` is the instance name, so the defaults
+ * produce exactly the topics hm2mqtt has always used; anything else is the user's choice, and what
+ * is subscribed follows from the literal part of the set templates.
+ */
+const topicFields = {prefix: config.name};
+const renderStatus = compileTemplate(config.topicStatus);
+const renderSet = compileTemplate(config.topicSet);
+const renderSysvarStatus = compileTemplate(config.topicSysvarStatus);
+const renderSysvarSet = compileTemplate(config.topicSysvarSet);
+const renderProgramStatus = compileTemplate(config.topicProgramStatus);
+const renderProgramSet = compileTemplate(config.topicProgramSet);
+/** what the plain mirror tree calls an item: the status topic without the `<name>/status/` head */
+const plainItem = (topic) => {
+    const head = `${config.name}/status/`;
+    return topic.startsWith(head) ? topic.slice(head.length) : topic;
+};
 const adapter = createAdapter({
     pkg,
     config,
@@ -142,7 +168,10 @@ const adapter = createAdapter({
             description: (iface, address) => metadata.description(iface, address, 'VALUES'),
             channelName,
             rooms: (address) => (regaSync ? regaSync.rooms(address) : undefined),
-            itemFor: (iface, address, datapoint) => renderItem(values.fields(iface, address, datapoint)).name,
+            statusTopicFor: (iface, address, datapoint) =>
+                renderStatus({...values.fields(iface, address, datapoint), ...topicFields}).name,
+            setTopicFor: (iface, address, datapoint) =>
+                renderSet({...values.fields(iface, address, datapoint), ...topicFields}).name,
             ignored,
             interfaces: enabled,
         }),
@@ -153,11 +182,25 @@ const adapter = createAdapter({
         rega: Boolean(regaSync),
         payload: payloadFormat,
     }),
-    onSet: handleSet,
+    /*
+     * Set topics are configurable, and the core owns `<name>/set/#`: it intercepts that namespace
+     * before the listen list and returns whether or not `onSet` is defined. So a template that
+     * stays under `<name>/set/` has to be served through onSet, and only one that moves elsewhere
+     * needs a listen pattern. onSet is handed the whole topic as its third argument, which is what
+     * the index is keyed by.
+     */
+    onSet: (parts, value, topic) => handleSetTopic(topic, value),
+    listen: Object.fromEntries(
+        [...new Set([config.topicSet, config.topicSysvarSet, config.topicProgramSet])]
+            .map((template) => subscribePattern(template, topicFields))
+            .filter((pattern) => !pattern.startsWith(`${config.name}/set/`))
+            .map((pattern) => [pattern, handleSetTopic]),
+    ),
     subscriptions: {
         'paramset/#': handleParamset,
         ...(config.rpcTopics ? {'rpc/+/+/+': handleRpc} : {}),
     },
+    onMqttConnect: () => republishTopics(),
     onShutdown: shutdown,
 });
 const {log, pubStatus} = adapter;
@@ -208,10 +251,19 @@ const values = new ValueStore({
 });
 values.load();
 
-const renderItem = compileTemplate(config.itemTemplate);
-const renderSysvarItem = compileTemplate(config.sysvarItemTemplate);
-const renderProgramItem = compileTemplate(config.programItemTemplate);
-const itemIndex = new ItemIndex();
+/** full set topic -> what to write; rebuilt whenever names or devices change */
+const topicIndex = new ItemIndex();
+
+/*
+ * Publishing is ours rather than the core's pubStatus, because that one owns the topic
+ * (`<name>/status/<item>`) and here the topic is configurable. The tracker is the core's, so the
+ * payload shapes, change detection and the retained cache behave exactly as before.
+ */
+const status = new StatusTracker({json: config.jsonPayloads});
+function publishTopic(topic, value, {retain = true, extra, ts, lc} = {}) {
+    const {payload} = status.update(topic, value, {retain, extra, ts, lc});
+    adapter.publish(topic, payload, {retain});
+}
 let indexTimer = null;
 
 let enabled = [];
@@ -237,10 +289,11 @@ function itemOf(name) {
 }
 
 function rendered(render, fields, label) {
-    const {name: item, changed} = render(fields);
+    // every template may use ${prefix}
+    const {name: item, changed} = render({...fields, ...topicFields});
     if (changed && !warnedNames.has(label)) {
         warnedNames.add(label);
-        log.warn('item of', label, 'rendered with replacements as', JSON.stringify(item));
+        log.warn('topic of', label, 'rendered with replacements as', JSON.stringify(item));
     }
     return item;
 }
@@ -251,8 +304,8 @@ function rendered(render, fields, label) {
  */
 function rebuildIndex() {
     indexTimer = null;
-    itemIndex.clear('datapoint');
-    itemIndex.collisions.clear();
+    topicIndex.clear('datapoint');
+    topicIndex.collisions.clear();
     for (const iface of Object.keys(metadata.devices)) {
         for (const [address, device] of Object.entries(metadata.devices[iface])) {
             if (!device.PARENT) {
@@ -264,20 +317,22 @@ function rebuildIndex() {
             }
             for (const datapoint of Object.keys(description)) {
                 const target = {kind: 'datapoint', address, datapoint};
-                itemIndex.add(renderItem(values.fields(iface, address, datapoint)).name, target);
-                itemIndex.add(`${address}/${datapoint}`, target);
+                const fields = {...values.fields(iface, address, datapoint), ...topicFields};
+                topicIndex.add(renderSet(fields).name, target);
+                // the address form stays addressable whatever the template says
+                topicIndex.add(`${config.name}/set/${address}/${datapoint}`, target);
             }
         }
     }
-    if (itemIndex.collisions.size > 0) {
-        const list = [...itemIndex.collisions.keys()];
+    if (topicIndex.collisions.size > 0) {
+        const list = [...topicIndex.collisions.keys()];
         log.warn(
             'items shared by several channels (the first one wins on set):',
             list.slice(0, 10).join(', '),
             list.length > 10 ? `… ${list.length - 10} more` : '',
         );
     }
-    log.debug('item index rebuilt:', itemIndex.size, 'items');
+    log.debug('topic index rebuilt:', topicIndex.size, 'topics');
     adapter.markDiscoveryDirty();
     adapter.publishDiscovery();
 }
@@ -297,19 +352,30 @@ function publishPlain(item, value, retain) {
 }
 
 function publishMessage(message, {retain = true} = {}) {
-    const item = rendered(renderItem, message, message.datapointName);
+    const topic = rendered(renderStatus, message, message.datapointName);
     const extra = withHm ? {hm: hmBlock(message)} : undefined;
-    pubStatus(item, outValue(message.value), {retain, extra, ts: message.ts, lc: message.lc});
-    publishPlain(item, message.value, retain);
+    publishTopic(topic, outValue(message.value), {retain, extra, ts: message.ts, lc: message.lc});
+    publishPlain(plainItem(topic), message.value, retain);
 }
 
 function publishRega(message) {
-    const render = message.type === 'PROGRAM' ? renderProgramItem : renderSysvarItem;
-    const item = rendered(render, message, `${message.type} ${message.name}`);
-    itemIndex.add(item, {kind: message.type === 'PROGRAM' ? 'program' : 'sysvar', name: message.name});
+    const program = message.type === 'PROGRAM';
+    const label = `${message.type} ${message.name}`;
+    const topic = rendered(program ? renderProgramStatus : renderSysvarStatus, message, label);
+    const setTopic = rendered(program ? renderProgramSet : renderSysvarSet, message, label);
+    topicIndex.add(setTopic, {kind: program ? 'program' : 'sysvar', name: message.name});
     const extra = withHm ? {hm: hmBlock(message)} : undefined;
-    pubStatus(item, outValue(message.value), {retain: true, extra, ts: message.ts, lc: message.lc});
-    publishPlain(item, message.value, true);
+    publishTopic(topic, outValue(message.value), {retain: true, extra, ts: message.ts, lc: message.lc});
+    publishPlain(plainItem(topic), message.value, true);
+}
+
+/** Every configurable topic we published, again - the core does this only for its own items. */
+function republishTopics() {
+    for (const topic of status.state.keys()) {
+        if (status.isRetained(topic)) {
+            adapter.publish(topic, status.payload(topic), {retain: true});
+        }
+    }
 }
 
 function publishItem(item, value, {retain = true} = {}) {
@@ -479,13 +545,25 @@ async function setValue(address, datapoint, value) {
     return throttled(`${iface}.${address}.${datapoint}`, () => conn.methodCall('setValue', [address, datapoint, cast]));
 }
 
-async function handleSet(parts, value, topic) {
+/**
+ * A write on one of the configured set topics. The topic arrives whole, because a rendered level
+ * may contain slashes and the subscription is therefore `<literal>/#`: the topic is looked up as it
+ * is, and only when that misses does the positional form after `<name>/set/` get a chance
+ * (`hm/set/ABC1234567:1/STATE`, `hm/set/rega/sync`).
+ * @param {string} topic
+ * @param {*} value
+ */
+async function handleSetTopic(topic, value) {
     if (value === undefined) {
         log.warn('mqtt ignoring empty payload on', topic);
         return;
     }
-    // exact item first (rendered template, address form, variables, programs), then the positional form
-    const target = itemIndex.get(parts.join('/')) || resolveSet(parts, lookup);
+    let target = topicIndex.get(topic);
+    if (!target) {
+        const remainder = templateRemainder(config.topicSet, topic, topicFields);
+        const positional = remainder === null ? null : remainder.split('/').filter(Boolean);
+        target = positional && positional.length > 0 ? resolveSet(positional, lookup) : null;
+    }
     if (!target) {
         throw new Error('unknown channel, variable or program');
     }

package/lib/hadiscovery.js

@@ -20,7 +20,8 @@ const TILT_TYPES = /BLIND/;
  * @property {(iface: string, address: string) => object | undefined} description VALUES description of a channel
  * @property {(address: string) => string | undefined} channelName
  * @property {(address: string) => string[] | undefined} rooms
- * @property {(iface: string, address: string, datapoint: string) => string} itemFor rendered item of a datapoint
+ * @property {(iface: string, address: string, datapoint: string) => string} statusTopicFor status topic of a datapoint
+ * @property {(iface: string, address: string, datapoint: string) => string} setTopicFor set topic of a datapoint
  * @property {(iface: string, address: string, datapoint: string) => boolean} [ignored]
  * @property {string[]} [interfaces] enabled interfaces (bridge entities)
  */
@@ -61,12 +62,14 @@ function labelOf(channel, deviceName, fallback) {
  * @returns {object[]} device blocks ({id, device, components, availability})
  */
 export function discoveryModel(ctx) {
-    const {adapterName, name, jsonPayloads: json = true, devices, itemFor} = ctx;
+    const {adapterName, name, jsonPayloads: json = true, devices, statusTopicFor, setTopicFor} = ctx;
     const ignored = ctx.ignored || (() => false);
     const t = templates(json);
     const bridgeId = discoveryId(adapterName, name);
-    const st = (iface, address, dp) => `${name}/status/${itemFor(iface, address, dp)}`;
-    const cmd = (iface, address, dp) => `${name}/set/${itemFor(iface, address, dp)}`;
+    // whole topics, from the configured templates - a controller has to be told where the values
+    // actually are, not where the convention would put them
+    const st = (iface, address, dp) => statusTopicFor(iface, address, dp);
+    const cmd = (iface, address, dp) => setTopicFor(iface, address, dp);
     const blocks = [];
 
     // the CCU / bridge device
@@ -148,7 +151,7 @@ function deviceBlock({iface, device, list, ctx, t, st, cmd, bridgeId, ignored})
             entity({
                 id,
                 name,
-                item: ctx.itemFor(iface, ch.ADDRESS, dp),
+                item: ctx.statusTopicFor(iface, ch.ADDRESS, dp),
                 platform,
                 label,
                 uid: `${ch.index}_${dp}`,

package/lib/topics.js

@@ -5,6 +5,19 @@
  * counter/<iface>/rx|tx, interface/<iface>/connected, <ifaceAddress>/DUTY_CYCLE.
  */
 
+/*
+ * Topics are templates, and the whole topic is one: `${prefix}` is the instance name, so a
+ * datapoint's status topic is `${prefix}/status/${channelName|channel}/${datapoint}` by default -
+ * exactly the topic hm2mqtt has always published, now written out where it can be changed.
+ */
+export const DEFAULT_TOPIC_STATUS = '${prefix}/status/${channelName|channel}/${datapoint}';
+export const DEFAULT_TOPIC_SET = '${prefix}/set/${channelName|channel}/${datapoint}';
+export const DEFAULT_TOPIC_SYSVAR_STATUS = '${prefix}/status/${name}';
+export const DEFAULT_TOPIC_SYSVAR_SET = '${prefix}/set/${name}';
+export const DEFAULT_TOPIC_PROGRAM_STATUS = '${prefix}/status/${name}';
+export const DEFAULT_TOPIC_PROGRAM_SET = '${prefix}/set/${name}';
+
+/** The item part of the classic topics, kept for `--item-template` and for the plain mirror tree. */
 export const DEFAULT_ITEM_TEMPLATE = '${channelName|channel}/${datapoint}';
 export const DEFAULT_SYSVAR_ITEM_TEMPLATE = '${name}';
 export const DEFAULT_PROGRAM_ITEM_TEMPLATE = '${name}';
@@ -209,3 +222,71 @@ export class ItemIndex {
         return this.items.size;
     }
 }
+
+/**
+ * The subscription a set template needs. Everything up to the first placeholder is literal and can
+ * be subscribed exactly; the rest becomes `#`, because a rendered level may itself contain slashes
+ * (a channel named "Haus/OG/Licht" is legitimate) and no fixed number of `+` levels would match it.
+ * The incoming topic is then resolved by exact lookup, not by position.
+ *
+ * `${prefix}/set/${channelName|channel}/${datapoint}` with prefix "hm" → `hm/set/#`.
+ *
+ * @param {string} template
+ * @param {object} fields values known before anything is rendered, normally `{prefix}`
+ * @returns {string} an mqtt subscription pattern
+ */
+export function subscribePattern(template, fields = {}) {
+    let text = String(template);
+    for (const [key, value] of Object.entries(fields)) {
+        text = text.split('${' + key + '}').join(String(value));
+    }
+    const placeholder = text.indexOf('${');
+    if (placeholder === -1) {
+        return text;
+    }
+    const literal = text.slice(0, placeholder);
+    const cut = literal.lastIndexOf('/');
+    return cut === -1 ? '#' : literal.slice(0, cut + 1) + '#';
+}
+
+/**
+ * Is `topic` below the literal part of `template`? Used to decide whether a set topic may fall back
+ * to the positional form (`<prefix>/set/<address>/<datapoint>`) when it is not in the index.
+ * @param {string} template
+ * @param {string} topic
+ * @param {object} fields
+ * @returns {string | null} the remainder after the literal prefix, or null
+ */
+export function templateRemainder(template, topic, fields = {}) {
+    const pattern = subscribePattern(template, fields);
+    if (!pattern.endsWith('#')) {
+        return topic === pattern ? '' : null;
+    }
+    const literal = pattern.slice(0, -1);
+    return topic.startsWith(literal) ? topic.slice(literal.length) : null;
+}
+
+/**
+ * `--item-template` and its two siblings named the part after `<name>/status/`. They still work:
+ * an item template becomes the corresponding pair of topic templates, so an existing config keeps
+ * publishing exactly where it did.
+ * @param {object} config
+ * @returns {object} the same config, with the topic templates filled in
+ */
+export function applyItemTemplates(config) {
+    const pairs = [
+        ['itemTemplate', 'topicStatus', 'topicSet'],
+        ['sysvarItemTemplate', 'topicSysvarStatus', 'topicSysvarSet'],
+        ['programItemTemplate', 'topicProgramStatus', 'topicProgramSet'],
+    ];
+    for (const [item, status, set] of pairs) {
+        if (!config[item]) {
+            continue;
+        }
+        config.$deprecated = config.$deprecated || [];
+        config.$deprecated.push(item);
+        config[status] = '${prefix}/status/' + config[item];
+        config[set] = '${prefix}/set/' + config[item];
+    }
+    return config;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hm2mqtt",
-  "version": "3.4.6",
+  "version": "3.5.0",
   "description": "Interface between Homematic CCU and MQTT",
   "type": "module",
   "main": "index.js",
@@ -73,6 +73,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
+    "aedes": "^1.1.2",
     "eslint": "^9.0.0",
     "eslint-config-prettier": "^10.0.0",
     "globals": "^16.0.0",

package/scripts/addon-api.js

@@ -10,7 +10,7 @@
  *   node scripts/addon-api.js probe      --host 127.0.0.1 [--tls]
  *   node scripts/addon-api.js mqtt-test  --url mqtt://host:1883 [--username u] [--password p]
  *   node scripts/addon-api.js channels   --host 127.0.0.1 [--limit 20]
- *   node scripts/addon-api.js preview    --host 127.0.0.1 --template '${channelName|channel}/${datapoint}'
+ *   node scripts/addon-api.js preview    --host 127.0.0.1 --template '${prefix}/status/${channelName|channel}/${datapoint}' [--prefix hm]
  *
  * Errors are JSON too ({"error": "..."}), so the UI never has to parse a stack trace.
  */
@@ -19,7 +19,7 @@ import Rega from 'homematic-rega';
 import {discover} from 'mqtt-interfaces-core';
 import {probeInterfaces, detectLocal, INTERFACE_NAMES} from '../lib/interfaces.js';
 import {discoveryHint, interfacesOf} from '../lib/discovery.js';
-import {compileTemplate, DEFAULT_ITEM_TEMPLATE} from '../lib/topics.js';
+import {compileTemplate, DEFAULT_TOPIC_STATUS} from '../lib/topics.js';
 
 const [command, ...rest] = process.argv.slice(2);
 
@@ -127,7 +127,8 @@ const commands = {
     },
 
     async preview() {
-        const template = String(args.template || DEFAULT_ITEM_TEMPLATE);
+        const template = String(args.template || DEFAULT_TOPIC_STATUS);
+        const prefix = String(args.prefix || 'hm');
         const render = compileTemplate(template);
         const limit = Number(args.limit || 5);
         const channels = await rega(args).getChannels();
@@ -135,6 +136,7 @@ const commands = {
         const examples = channels.slice(0, limit).map((ch, index) => {
             const datapoint = datapoints[index % datapoints.length];
             const fields = {
+                prefix,
                 channel: ch.address,
                 channelName: ch.name,
                 device: String(ch.address).split(':')[0],