{"id":50407850,"url":"https://github.com/labodj/labo-smart-home-coordinator","last_synced_at":"2026-05-31T02:08:06.321Z","repository":{"id":354857247,"uuid":"1225379637","full_name":"labodj/labo-smart-home-coordinator","owner":"labodj","description":"Standalone MQTT coordinator for devices implementing the public LSH protocol contract.","archived":false,"fork":false,"pushed_at":"2026-05-28T18:57:06.000Z","size":670,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T20:25:23.361Z","etag":null,"topics":["coordinator","home-automation","labo-smart-home","lsh","lsh-protocol","mqtt","nodejs","smart-home","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/labo-smart-home-coordinator","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/labodj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-30T08:09:49.000Z","updated_at":"2026-05-28T18:57:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/labodj/labo-smart-home-coordinator","commit_stats":null,"previous_names":["labodj/labo-smart-home-coordinator"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/labodj/labo-smart-home-coordinator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labodj%2Flabo-smart-home-coordinator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labodj%2Flabo-smart-home-coordinator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labodj%2Flabo-smart-home-coordinator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labodj%2Flabo-smart-home-coordinator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/labodj","download_url":"https://codeload.github.com/labodj/labo-smart-home-coordinator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/labodj%2Flabo-smart-home-coordinator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33716342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coordinator","home-automation","labo-smart-home","lsh","lsh-protocol","mqtt","nodejs","smart-home","typescript"],"created_at":"2026-05-31T02:08:05.566Z","updated_at":"2026-05-31T02:08:06.315Z","avatar_url":"https://github.com/labodj.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Labo Smart Home Coordinator\n\n[![npm](https://img.shields.io/npm/v/labo-smart-home-coordinator.svg)](https://www.npmjs.com/package/labo-smart-home-coordinator)\n[![npm downloads](https://img.shields.io/npm/dm/labo-smart-home-coordinator.svg)](https://www.npmjs.com/package/labo-smart-home-coordinator)\n[![CI](https://github.com/labodj/labo-smart-home-coordinator/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/labodj/labo-smart-home-coordinator/actions/workflows/ci.yaml)\n[![Node.js](https://img.shields.io/node/v/labo-smart-home-coordinator.svg)](https://www.npmjs.com/package/labo-smart-home-coordinator)\n[![Latest Release](https://img.shields.io/github/v/release/labodj/labo-smart-home-coordinator?display_name=tag\u0026sort=semver)](https://github.com/labodj/labo-smart-home-coordinator/releases/latest)\n[![License](https://img.shields.io/github/license/labodj/labo-smart-home-coordinator.svg)](https://github.com/labodj/labo-smart-home-coordinator/blob/main/LICENSE)\n\n[![works with MQTT Homie](https://homieiot.github.io/img/works-with-homie.svg \"works with MQTT Homie\")](https://homieiot.github.io/)\n\n`labo-smart-home-coordinator` is the standalone TypeScript runtime for the\npublic LSH MQTT coordination contract. It listens to LSH device telemetry, keeps\na live registry, validates distributed long-click actions, emits actuator\ncommands, publishes alerts, and exposes generic intents for non-LSH devices.\n\nIn practical terms, it answers one careful question: a button was long-pressed,\nso what can be switched with the state available right now?\n\n## Why This Exists\n\nLSH devices already publish their configuration, state, Homie lifecycle, and\nclick events over MQTT. This package adds the focused runtime that coordinates\nacross devices and rejects actions when the required state is not reliable.\n\nIt keeps that responsibility focused:\n\n- the config names the LSH devices and the click actions you want;\n- the coordinator checks whether target state is fresh enough to act;\n- LSH commands, alerts, and external actor intents stay separate;\n- Home Assistant entities, dashboards, and integration-specific commands remain\n  outside the core runtime.\n\nYou can run it as a CLI process, embed it in a Node.js service, or use it\nthrough the Node-RED wrapper package.\n\n## Install\n\n```bash\nnpm install labo-smart-home-coordinator\n```\n\nNode.js 18 or newer is required.\n\n## Run It from the CLI\n\nThe CLI owns the MQTT connection for you:\n\n```bash\nnpx labo-smart-home-coordinator \\\n  --broker mqtt://localhost:1883 \\\n  --config ./system-config.json\n```\n\nWith authentication and MQTT v5:\n\n```bash\nnpx labo-smart-home-coordinator \\\n  --broker mqtt://192.168.1.20:1883 \\\n  --username homie \\\n  --password homie \\\n  --mqtt-version 5 \\\n  --config ./system-config.json\n```\n\nTLS and mutual TLS are supported:\n\n```bash\nnpx labo-smart-home-coordinator \\\n  --broker mqtts://mqtt.example.net:8883 \\\n  --ca ./certs/ca.pem \\\n  --cert ./certs/client.crt \\\n  --key ./certs/client.key \\\n  --config ./system-config.json\n```\n\n## Use It as a Library\n\nUse the transport-agnostic runtime when your application already owns MQTT or\nwants to feed messages from another source:\n\n```ts\nimport { LaboSmartHomeCoordinator } from \"labo-smart-home-coordinator\";\n\nconst coordinator = new LaboSmartHomeCoordinator({\n  systemConfig,\n  homieBasePath: \"homie/5/\",\n  lshBasePath: \"LSH/\",\n});\n\ncoordinator.on(\"mqtt\", (message) =\u003e mqttClient.publish(message.topic!, message.payload));\ncoordinator.on(\"alert\", (alert) =\u003e console.warn(alert.message));\ncoordinator.on(\"otherActors\", (command) =\u003e routeExternalActors(command));\n\nawait coordinator.start();\nawait coordinator.processMqttMessage({\n  topic: \"LSH/cucina/state\",\n  payload: { p: 2, s: [1] },\n});\n```\n\nUse the MQTT adapter when you want the package to own the broker connection:\n\n```ts\nimport { LaboSmartHomeCoordinatorMqtt } from \"labo-smart-home-coordinator/mqtt\";\n\nconst runtime = new LaboSmartHomeCoordinatorMqtt({\n  brokerUrl: \"mqtt://localhost:1883\",\n  systemConfig,\n  otherActorsTopic: \"home/other-actors/commands\",\n  alertsTopic: \"home/alerts\",\n});\n\nawait runtime.start();\n```\n\n## Minimal Config\n\nThe config file lists the LSH devices the coordinator should know about and the\nbutton actions it should execute.\n\n```json\n{\n  \"devices\": [\n    {\n      \"name\": \"ingresso\",\n      \"longClickButtons\": [\n        {\n          \"id\": 1,\n          \"actors\": [\n            {\n              \"name\": \"cucina\",\n              \"allActuators\": true,\n              \"actuators\": []\n            }\n          ],\n          \"otherActors\": [\"zigbee_table_lamp\"]\n        }\n      ]\n    },\n    {\n      \"name\": \"cucina\"\n    }\n  ]\n}\n```\n\nThat means: when device `ingresso` reports a long click on button `1`, toggle\nall actuators on device `cucina` and also emit an intent for\n`zigbee_table_lamp`.\n\n## Runtime Behavior\n\nThe coordinator is conservative by design. It reuses retained `conf` and\n`state` snapshots, but it does not treat retained lifecycle traffic as proof\nthat a device is alive right now. A distributed click is confirmed only when the\ntarget state is authoritative, and recovery probes are rate-limited so an\nunreachable device does not flood the broker.\n\nIt subscribes to `conf`, `state`, `events`, `bridge`, and Homie `$state` topics\nfor every configured device. It publishes LSH commands to device `IN` topics and\nbridge-wide probes to the configured service topic.\n\nUse `--validate-config`, `--print-effective-config`, or\n`--explain-subscriptions` to inspect a generated config without connecting to\nMQTT. The subscription QoS policy is configurable through `subscriptionQos` in\nlibrary mode or the `--qos-*` CLI flags. Send `SIGHUP` to the standalone CLI\nprocess to reload the JSON config file without reconnecting MQTT.\n\n## Documentation\n\nThe full documentation map lives in\n[DOCS.md](https://github.com/labodj/labo-smart-home-coordinator/blob/main/DOCS.md).\nStart there for configuration, CLI options, embedding, MQTT behavior, and the\nlifecycle contract.\n\nThe Node-RED sibling is\n[`node-red-contrib-lsh-logic`](https://flows.nodered.org/node/node-red-contrib-lsh-logic).\nIt wraps this runtime with Node-RED editor fields, context access, dynamic MQTT\nsubscriptions, and physical outputs.\n\n## Maintainer Notes\n\nThe local quality gate runs type checking, linting, Markdown checks, formatting\nchecks, package validation, coverage, and a production dependency audit:\n\n```bash\nnpm ci\nnpm run check\n```\n\n## License\n\nApache-2.0. See\n[LICENSE](https://github.com/labodj/labo-smart-home-coordinator/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flabodj%2Flabo-smart-home-coordinator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flabodj%2Flabo-smart-home-coordinator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flabodj%2Flabo-smart-home-coordinator/lists"}