mqttpc 2.0.0 → 2.1.0

package/README.md

@@ -86,6 +86,29 @@ that changing a process away from a retained mode leaves the old message on the
 | `<name>/connected`                            | `2` running · `0` stopped                                              |
 | `<name>/info`                                 | the procs file, the process names, what is running, whether it is root |
 
+## Home Assistant
+
+Every process becomes **one HA device**, hanging off a bridge device for the instance:
+
+| Entity                     | Platform        | What it does                                      |
+| -------------------------- | --------------- | ------------------------------------------------- |
+| **Running**                | `binary_sensor` | on while there is a pid (`device_class: running`) |
+| **Start**                  | `button`        | publishes to `set/<proc>/spawn`                   |
+| **Stop**                   | `button`        | `SIGTERM`                                         |
+| **Kill**                   | `button`        | `SIGKILL`, diagnostic                             |
+| PID, Last exit, Last error | `sensor`        | diagnostics                                       |
+
+The bridge device carries a **Running processes** count. Discovery is published once at start, since
+the device set comes from the procs file; `--no-ha-discovery` turns it off and clears what was
+announced.
+
+The Start button presses an **empty** payload rather than HA's default `PRESS`, so a process with
+`stdinFromSpawnPayload` does not receive the word "PRESS" on stdin.
+
+There is deliberately no entity for `stdout` / `stderr`: an HA sensor state is capped at 255
+characters and process output routinely exceeds that, so such an entity would spend its life logging
+errors. Use the MQTT topics for output.
+
 ## Security
 
 **mqttpc turns "may publish to `<name>/set/#`" into "may run these programs on this host".** That is
@@ -145,6 +168,7 @@ entry can work, since a process that is not root cannot become another user.
 | `-u, --mqtt-url`   | `mqtt://localhost` | broker url                                         |
 | `-n, --name`       | `pc`               | instance name = topic prefix                       |
 | `--root`           | `false`            | `--install` runs the service as root (discouraged) |
+| `--ha-discovery`   | `true`             | announce the processes to Home Assistant           |
 | `-v, --verbosity`  | `info`             | `error`, `warn`, `info`, `debug`                   |
 
 `--help` lists the shared options too, and `--config-schema` prints the JSON Schema a management UI

package/index.js

@@ -18,6 +18,7 @@ import {handle as handleInstall, ROOT_WARNING} from './lib/install.js';
 import {loadProcs, needsRoot} from './lib/procs.js';
 import {createRunner} from './lib/runner.js';
 import {createDispatch} from './lib/dispatch.js';
+import {discoveryModel} from './lib/hadiscovery.js';
 
 handleInstall(config); // --install / --uninstall never reach the rest
 
@@ -44,6 +45,10 @@ const adapter = createAdapter({
         running: runner ? runner.names : [],
         root: isRoot,
     }),
+    // one HA device per process, plus the bridge they hang off. The set is fixed once the procs
+    // file is read, so there is nothing to re-trigger it on.
+    discovery: () =>
+        discoveryModel({name: config.name, procs, jsonPayloads: config.jsonPayloads, version: pkg.version}),
     onSet: (...args) => dispatch(...args),
     // children of a process controller outlive nothing: stop them with it
     onShutdown: () => runner.stopAll(),
@@ -54,8 +59,10 @@ runner = createRunner({
     log: adapter.log,
     isRoot,
     publish: (item, value, options) => adapter.pubStatus(item, value, options),
+    onChange: () => adapter.pubStatus('bridge/running', runner.names.length),
 });
 dispatch = createDispatch({procs, runner, log: adapter.log});
+adapter.pubStatus('bridge/running', 0);
 
 if (isRoot) {
     adapter.log.warn(ROOT_WARNING.replace('<name>', config.name));

package/lib/hadiscovery.js

@@ -0,0 +1,102 @@
+/**
+ * Home Assistant discovery: one bridge device plus one device per process in the procs file,
+ * linked with `via_device`.
+ *
+ * Pure — processes in, device blocks out; the core publishes them. The set is fixed once the procs
+ * file is read, so this is built once rather than on a trigger.
+ *
+ * What a process gets is what you actually do with one: start it, stop it, see whether it is
+ * running and how it ended. Deliberately **not** stdout/stderr — an HA sensor state is capped at
+ * 255 characters and process output routinely exceeds that, so those entities would spend their
+ * life logging errors. See ROADMAP.md.
+ */
+
+import {discoveryId, entity} from 'mqtt-interfaces-core';
+
+/** A device id may only hold these; a process name is looser (dots are legal in a topic level). */
+const idSafe = (text) => text.replace(/[^a-zA-Z0-9_-]/g, '_');
+
+/** `true` when the pid topic holds one, i.e. the process is running. An empty payload is not. */
+function runningTemplate(jsonPayloads) {
+    return jsonPayloads ? "{{ 'ON' if value_json.val else 'OFF' }}" : "{{ 'ON' if value else 'OFF' }}";
+}
+
+/**
+ * @param {object} input
+ * @param {string} input.name instance name / topic prefix
+ * @param {object} input.procs the validated procs file
+ * @param {boolean} [input.jsonPayloads]
+ * @param {string} [input.version] adapter version, shown as the bridge's firmware
+ * @returns {Array<object>} device blocks for the core's discovery publisher
+ */
+export function discoveryModel({name, procs, jsonPayloads = true, version}) {
+    const bridgeId = discoveryId('mqttpc', name);
+
+    const blocks = Object.entries(procs).map(([proc, def]) => {
+        const id = `${bridgeId}_${idSafe(proc)}`;
+        const e = (item, uid, platform, label, more = {}) =>
+            entity({id, name, item: `${proc}/${item}`, uid, platform, label, jsonPayloads, ...more});
+
+        return {
+            id,
+            device: {
+                name: proc,
+                mf: 'mqttpc',
+                // the program is what this device actually is
+                mdl: def.path,
+                via_device: bridgeId,
+            },
+            components: {
+                running: e('pid', 'running', 'binary_sensor', 'Running', {
+                    extra: {dev_cla: 'running', val_tpl: runningTemplate(jsonPayloads)},
+                }),
+                start: e('spawn', 'start', 'button', 'Start', {
+                    command: true,
+                    icon: 'mdi:play',
+                    // the default "PRESS" would be written to stdin of a stdinFromSpawnPayload entry
+                    extra: {pl_prs: ''},
+                }),
+                stop: e('signal', 'stop', 'button', 'Stop', {
+                    command: true,
+                    icon: 'mdi:stop',
+                    extra: {pl_prs: 'SIGTERM'},
+                }),
+                kill: e('signal', 'kill', 'button', 'Kill', {
+                    command: true,
+                    icon: 'mdi:skull',
+                    category: 'diagnostic',
+                    extra: {pl_prs: 'SIGKILL'},
+                }),
+                pid: e('pid', 'pid', 'sensor', 'PID', {category: 'diagnostic', icon: 'mdi:identifier'}),
+                exit: e('exit', 'exit', 'sensor', 'Last exit', {
+                    category: 'diagnostic',
+                    icon: 'mdi:flag-checkered',
+                }),
+                error: e('error', 'error', 'sensor', 'Last error', {
+                    category: 'diagnostic',
+                    icon: 'mdi:alert-circle-outline',
+                }),
+            },
+        };
+    });
+
+    const bridge = {
+        id: bridgeId,
+        device: {mf: 'mqttpc', mdl: 'process control', ...(version && {sw: version})},
+        components: {
+            running: entity({
+                id: bridgeId,
+                name,
+                item: 'bridge/running',
+                uid: 'running',
+                platform: 'sensor',
+                label: 'Running processes',
+                category: 'diagnostic',
+                icon: 'mdi:cog-play',
+                jsonPayloads,
+            }),
+        },
+    };
+
+    return [bridge, ...blocks];
+}

package/lib/runner.js

@@ -48,9 +48,10 @@ export function outputMode(proc, stream) {
  * @param {object} options.log
  * @param {(item: string, value: *, opts?: object) => void} options.publish `<name>/status/<item>`
  * @param {boolean} [options.isRoot] whether uid/gid in an entry can be honoured
+ * @param {() => void} [options.onChange] called whenever something starts or stops
  * @param {Function} [options.spawn] for tests
  */
-export function createRunner({procs, log, publish, isRoot = false, spawn = nodeSpawn}) {
+export function createRunner({procs, log, publish, isRoot = false, onChange = () => {}, spawn = nodeSpawn}) {
     /** name → the running ChildProcess. Absent means not running. */
     const running = new Map();
     /** name → payloads waiting for their turn (`enqueueSpawns`). */
@@ -146,6 +147,7 @@ export function createRunner({procs, log, publish, isRoot = false, spawn = nodeS
             statusOf(name, 'error', error.message);
             statusOf(name, 'pid', '');
             running.delete(name);
+            onChange();
         });
 
         for (const stream of ['stdout', 'stderr']) {
@@ -169,6 +171,7 @@ export function createRunner({procs, log, publish, isRoot = false, spawn = nodeS
             // `code` is null when a signal killed it — 1.x tested `typeof code === null`, which is
             // never true, so the signal never made it out
             statusOf(name, 'exit', signal === null || signal === undefined ? code : signal);
+            onChange();
             const queue = queues.get(name);
             if (queue && queue.length > 0) {
                 log.info(name, 'finished; starting the next queued run');
@@ -180,6 +183,7 @@ export function createRunner({procs, log, publish, isRoot = false, spawn = nodeS
             log.info(name, 'started', proc.path, 'as pid', child.pid);
             statusOf(name, 'pid', child.pid);
         }
+        onChange();
         if (proc.stdinFromSpawnPayload && child.stdin) {
             // one-shot: the payload is the whole input, so close stdin or the program waits for EOF
             child.stdin.write(String(payload));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mqttpc",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Control processes on a host via MQTT. Follows the mqtt-smarthome architecture.",
   "type": "module",
   "main": "index.js",
@@ -54,7 +54,7 @@
     "serviceExtra": []
   },
   "dependencies": {
-    "mqtt-interfaces-core": "^0.14.0"
+    "mqtt-interfaces-core": "^0.15.0"
   },
   "devDependencies": {
     "@eslint/js": "^9",