https://github.com/labodj/labo-smart-home-coordinator
Standalone MQTT coordinator for devices implementing the public LSH protocol contract.
https://github.com/labodj/labo-smart-home-coordinator
coordinator home-automation labo-smart-home lsh lsh-protocol mqtt nodejs smart-home typescript
Last synced: 17 days ago
JSON representation
Standalone MQTT coordinator for devices implementing the public LSH protocol contract.
- Host: GitHub
- URL: https://github.com/labodj/labo-smart-home-coordinator
- Owner: labodj
- License: apache-2.0
- Created: 2026-04-30T08:09:49.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-28T18:57:06.000Z (19 days ago)
- Last Synced: 2026-05-28T20:25:23.361Z (19 days ago)
- Topics: coordinator, home-automation, labo-smart-home, lsh, lsh-protocol, mqtt, nodejs, smart-home, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/labo-smart-home-coordinator
- Size: 654 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff
- Notice: NOTICE
Awesome Lists containing this project
README
# Labo Smart Home Coordinator
[](https://www.npmjs.com/package/labo-smart-home-coordinator)
[](https://www.npmjs.com/package/labo-smart-home-coordinator)
[](https://github.com/labodj/labo-smart-home-coordinator/actions/workflows/ci.yaml)
[](https://www.npmjs.com/package/labo-smart-home-coordinator)
[](https://github.com/labodj/labo-smart-home-coordinator/releases/latest)
[](https://github.com/labodj/labo-smart-home-coordinator/blob/main/LICENSE)
[](https://homieiot.github.io/)
`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
```bash
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:
```bash
npx labo-smart-home-coordinator \
--broker mqtt://localhost:1883 \
--config ./system-config.json
```
With authentication and MQTT v5:
```bash
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:
```bash
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:
```ts
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:
```ts
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.
```json
{
"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](https://github.com/labodj/labo-smart-home-coordinator/blob/main/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`](https://flows.nodered.org/node/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:
```bash
npm ci
npm run check
```
## License
Apache-2.0. See
[LICENSE](https://github.com/labodj/labo-smart-home-coordinator/blob/main/LICENSE).