Labo Smart Home Coordinator

labo-smart-home-coordinator is the standalone TypeScript runtime for the public LSH MQTT coordination contract. It listens to LSH device telemetry, keeps a live registry, validates distributed long-click actions, emits actuator commands, publishes alerts, and exposes generic intents for non-LSH devices.

In practical terms, it answers one careful question: a button was long-pressed, so what can be switched with the state available right now?

Why This Exists

LSH devices already publish their configuration, state, Homie lifecycle, and click events over MQTT. This package adds the focused runtime that coordinates across devices and rejects actions when the required state is not reliable.

It keeps that responsibility focused:

• the config names the LSH devices and the click actions you want;
• the coordinator checks whether target state is fresh enough to act;
• LSH commands, alerts, and external actor intents stay separate;
• Home Assistant entities, dashboards, and integration-specific commands remain outside the core runtime.

You can run it as a CLI process, embed it in a Node.js service, or use it through the Node-RED wrapper package.

Install

npm install labo-smart-home-coordinator

Node.js 18 or newer is required.

Run It from the CLI

The CLI owns the MQTT connection for you:

npx labo-smart-home-coordinator \
  --broker mqtt://localhost:1883 \
  --config ./system-config.json

With authentication and MQTT v5:

npx labo-smart-home-coordinator \
  --broker mqtt://192.168.1.20:1883 \
  --username homie \
  --password homie \
  --mqtt-version 5 \
  --config ./system-config.json

TLS and mutual TLS are supported:

npx labo-smart-home-coordinator \
  --broker mqtts://mqtt.example.net:8883 \
  --ca ./certs/ca.pem \
  --cert ./certs/client.crt \
  --key ./certs/client.key \
  --config ./system-config.json

Use It as a Library

Use the transport-agnostic runtime when your application already owns MQTT or wants to feed messages from another source:

import { LaboSmartHomeCoordinator } from "labo-smart-home-coordinator";

const coordinator = new LaboSmartHomeCoordinator({
  systemConfig,
  homieBasePath: "homie/5/",
  lshBasePath: "LSH/",
});

coordinator.on("mqtt", (message) => mqttClient.publish(message.topic!, message.payload));
coordinator.on("alert", (alert) => console.warn(alert.message));
coordinator.on("otherActors", (command) => routeExternalActors(command));

await coordinator.start();
await coordinator.processMqttMessage({
  topic: "LSH/cucina/state",
  payload: { p: 2, s: [1] },
});

Use the MQTT adapter when you want the package to own the broker connection:

import { LaboSmartHomeCoordinatorMqtt } from "labo-smart-home-coordinator/mqtt";

const runtime = new LaboSmartHomeCoordinatorMqtt({
  brokerUrl: "mqtt://localhost:1883",
  systemConfig,
  otherActorsTopic: "home/other-actors/commands",
  alertsTopic: "home/alerts",
});

await runtime.start();

Minimal Config

The config file lists the LSH devices the coordinator should know about and the button actions it should execute.

{
  "devices": [
    {
      "name": "ingresso",
      "longClickButtons": [
        {
          "id": 1,
          "actors": [
            {
              "name": "cucina",
              "allActuators": true,
              "actuators": []
            }
          ],
          "otherActors": ["zigbee_table_lamp"]
        }
      ]
    },
    {
      "name": "cucina"
    }
  ]
}

That means: when device ingresso reports a long click on button 1, toggle all actuators on device cucina and also emit an intent for zigbee_table_lamp.

Runtime Behavior

The coordinator is conservative by design. It reuses retained conf and state snapshots, but it does not treat retained lifecycle traffic as proof that a device is alive right now. A distributed click is confirmed only when the target state is authoritative, and recovery probes are rate-limited so an unreachable device does not flood the broker.

It subscribes to conf, state, events, bridge, and Homie $state topics for every configured device. It publishes LSH commands to device IN topics and bridge-wide probes to the configured service topic.

Use --validate-config, --print-effective-config, or --explain-subscriptions to inspect a generated config without connecting to MQTT. The subscription QoS policy is configurable through subscriptionQos in library mode or the --qos-* CLI flags. Send SIGHUP to the standalone CLI process to reload the JSON config file without reconnecting MQTT.

Documentation

The full documentation map lives in DOCS.md. Start there for configuration, CLI options, embedding, MQTT behavior, and the lifecycle contract.

The Node-RED sibling is node-red-contrib-lsh-logic. It wraps this runtime with Node-RED editor fields, context access, dynamic MQTT subscriptions, and physical outputs.

Maintainer Notes

The local quality gate runs type checking, linting, Markdown checks, formatting checks, package validation, coverage, and a production dependency audit:

npm ci
npm run check

License

Apache-2.0. See LICENSE.