{"id":13799924,"url":"https://github.com/codmpm/node-red-contrib-loxone","last_synced_at":"2025-05-13T08:32:17.739Z","repository":{"id":18056319,"uuid":"83245239","full_name":"codmpm/node-red-contrib-loxone","owner":"codmpm","description":"Connect the Loxone Miniserver to node-red via the Websocket API","archived":false,"fork":false,"pushed_at":"2024-02-27T04:23:35.000Z","size":1162,"stargazers_count":71,"open_issues_count":13,"forks_count":24,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-03-15T09:21:30.108Z","etag":null,"topics":["home-automation","loxone","loxone-miniserver","node-red","smarthome","websockets"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codmpm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-02-26T22:27:10.000Z","updated_at":"2024-04-19T08:51:11.039Z","dependencies_parsed_at":"2024-04-19T08:51:00.156Z","dependency_job_id":null,"html_url":"https://github.com/codmpm/node-red-contrib-loxone","commit_stats":{"total_commits":136,"total_committers":12,"mean_commits":"11.333333333333334","dds":"0.16911764705882348","last_synced_commit":"f03e8c3d3944df55ace086010081e8f198784ce9"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codmpm%2Fnode-red-contrib-loxone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codmpm%2Fnode-red-contrib-loxone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codmpm%2Fnode-red-contrib-loxone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codmpm%2Fnode-red-contrib-loxone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codmpm","download_url":"https://codeload.github.com/codmpm/node-red-contrib-loxone/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253903904,"owners_count":21981766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["home-automation","loxone","loxone-miniserver","node-red","smarthome","websockets"],"created_at":"2024-08-04T00:01:07.222Z","updated_at":"2025-05-13T08:32:17.290Z","avatar_url":"https://github.com/codmpm.png","language":"HTML","funding_links":[],"categories":["Nodes"],"sub_categories":["Smarthome"],"readme":"# node-red-contrib-loxone\n\n\u003e **As of verison `0.10.4` please make sure, that your system has the `git` command installed, as the needed library are currently \n\u003epulled from github. Otherwise you will get an `undefined ls-remote`-Error.**  \n\n---\n\nThis node connects the Loxone Miniserver to node-red. It uses [node-lox-ws-api](https://github.com/alladdin/node-lox-ws-api) \nby Ladislav Dokulil based on Loxone's documenation for the [Websocket API](https://www.loxone.com/dede/wp-content/uploads/sites/2/2021/06/1201_Communicating-with-the-Miniserver.pdf).\n\nIt enables you to connect the Loxone Miniserver directly to node-red and work with the data\non occuring events. As this uses the official Websocket, you will only see controls that are \nvisualized in Loxone-Config. \n\n**You will get the data from Loxone's websocket _as is_. There is and will be no abstraction layer!**\n\nSo please know how to handle the data according to the [structure file](https://www.loxone.com/wp-content/uploads/datasheets/StructureFile.pdf) \nor the [webservice documenation](https://www.loxone.com/enen/kb/web-services/).\n\nAs of Loxone V9 the new token based authentification should be used. If you are still using V8 or earlier, please use `AES-256-CBC` or \n`Hash`. The \"old\" authentification methods will be supported by Loxone in version 9 till March 2018.\n\nKeepalive is handled via `node-lox-ws-api` and token based authentication is used if available.\n\nAs I don't have an own Loxone installation, I can't do a \"real world\" test. Gladly have an own miniserver through the \nmentioned crowdfunding campaign. Again, thank you all!\n\nTested with loxone-config V11.0.5.5, node-red 1.0.6, nodeJS 12.13.1 LTS\n\n\u003e Help, pull requests and feedback in general are very welcome!\n\n### Nodes\n* **Miniserver**: Configure a miniserver connection used by every other node.\n* **Control-In**: Select a control and a state to hook an event which then gets passed to node-red on occurence.\n* **Control-Out**: Select a control and feed it commands according to the [structure file](https://www.loxone.com/dede/wp-content/uploads/sites/2/2016/08/loxone-structure-file.pdf?x48792)\n* **Webservice**: Send direct webservice calls through the existing websocket, see the [webservice documenation](https://www.loxone.com/enen/kb/web-services/). \nPlease use URI's in form of `jdev/sps/io/foo` (no leading `/`), simply replace `dev/` from the documentation with `jdev/`. The returned\nvalue will be in `msg.payload`.\n* **Stream-In**: Receive all (!) occuring events from a selected room and/or category. Could be handy to put every temperature (e.g.) into \na database or something - see the node for more info.\n* **Stream-All**: Receive EVERY occuring event. __USE THIS WITH CAUTION!!__\n* **Online**: Emit's `true`/`false` for the state of the connection to the selected miniserver. Be careful as every failed \nconnection attempt sends a `false` over and over again till a connection could be established.\n* **Keepalive**: outputs the current time (in ms) from the keepalive request done by the underlying library (node-lox-ws-api) \nevery x seconds (as configured in the connection). See page 17 of the Loxone webservice documentation. The response time can be used to measssure connection \nquality.\n\nThe information used comes from the structure file, which can be retrieved from your miniserver via `http://\u003cminiserver\u003e/data/LoxAPP3.json`.\n\n`msg.payload` holds the value retrieved. The `msg`-object also has some additional information. \nIn general you will find the arrived data in `msg.payload`, but have a look at the complete `msg`-object of each node.\n\nAdded in `0.9.0` you will also have the miniserver information from the structure file in `msg.msInfo`. It is present in all nodes\nexcept the online-node, as the the structure file is not yet parsed when it emits it's state.\n\nYou will also have `lastModified`, which is the Date/Time when the program of the miniserver was uploaded. \n\nHere's example of the complete `msg`-object from a switch:\n    \n    {\n       \"payload\":1,\n       \"topic\":\"SchalterWZ\",\n       \"state\":\"active\",\n       \"room\":\"Wohnzimmer\",\n       \"category\":\"Beleuchtung\",\n       \"details\":null,\n       \"type\":\"Switch\",\n       \"isFavorite\":null,\n       \"isSecured\":null,\n       \"uuid\":\"10965a26-0124-4b62-ffff90eb033172c2\",\n       \"msInfo\":{\n          \"serialNr\":\"xxx\",\n          \"msName\":\"Loxone Miniserver\",\n          \"projectName\":\"nodelox\",\n          \"localUrl\":\"192.168.xx.xx\",\n          \"remoteUrl\":\"\",\n          \"tempUnit\":0,\n          \"currency\":\"€\",\n          \"squareMeasure\":\"m²\",\n          \"location\":\"xxx\",\n          \"languageCode\":\"DEU\",\n          \"heatPeriodStart\":\"10-01\",\n          \"heatPeriodEnd\":\"04-30\",\n          \"coolPeriodStart\":\"05-01\",\n          \"coolPeriodEnd\":\"09-30\",\n          \"catTitle\":\"Kategorie\",\n          \"roomTitle\":\"Raum\",\n          \"miniserverType\":0,\n          \"sortByRating\":false,\n          \"currentUser\":{\n             \"name\":\"admin\",\n             \"uuid\":\"0b734138-03da-047e-ffff403fb0c34b9e\",\n             \"isAdmin\":true,\n             \"changePassword\":true,\n             \"userRights\":2047\n          }\n       },\n       \"lastModified\":\"2017-11-30 21:13:58\",\n       \"_msgid\":\"f21030d7.2b112\"\n    }\n    \nOn the webservice-node there will also be `msg.data` if there is data other than `value` which is present in `payload`. \nFor example if you request `jdev/sps/io/\u003celement\u003e/All`:\n\n    {\n       \"payload\":\"0\",\n       \"topic\":\"dev/sps/io/Automatikjalousie/All\",\n       \"code\":200,\n       \"data\":{\n          \"StateUp\":0,\n          \"StateDown\":0,\n          \"StatePos\":1,\n          \"StateShade\":1,\n          \"StateAutoShade\":0,\n          \"StateSafety\":0,\n          \"value\":\"0\"\n       },\n       \"msInfo\":{ ... }\n       \"lastModified\":\"2017-11-30 21:13:58\",\n       \"_msgid\":\"752341c2.6eddd\"\n    }\n    \n    \n### Examples\n\n![image of node-red editor](https://github.com/codmpm/node-red-contrib-loxone/blob/master/node-red-contrib-loxone-editor.png?raw=true)\n![image node-red dashboard](https://github.com/codmpm/node-red-contrib-loxone/blob/master/node-red-contrib-loxone-dashboard.png?raw=true)\n\nHere's a small video of the controls above with the Loxone Webinterface on the left, Loxone-Config with LiveView enabled in the \nmiddle and node-red with node-red-dashboard on the right: https://cloud.codm.de/index.php/s/hNO2hIgnGIDWGqM\n\n--- \n\n![image of node-red flow for fritzbox](https://github.com/codmpm/node-red-contrib-loxone/blob/master/node-red-contrib-loxone-demo-fritz.png?raw=true)\n  \nAnother example: Reading the current used bandwith of a FritzBox-Router and display \nthis data in the visualisation of the Miniserver:  https://cloud.codm.de/index.php/s/5XoNoMLilinpU4v\n    \nThe flow itself could be found here: http://flows.nodered.org/flow/0b3c81b3361027ce4064d4e934f23685    \n\n---\n\n![image of node-red flow for webservice](https://github.com/codmpm/node-red-contrib-loxone/blob/master/node-red-contrib-loxone-webservice.png?raw=true)\nThe webservice node allows you to directly call webservice URI's through the already established websocket connection.\n\nYou can choose to automaticly append the incoming `msg.payload` to the set URI. \nThis is handy to add dynamic content to the webservice call, for example `DownOn` or `DownOff`.\n\nAs the `UpDownDigital` (etc.) virtual input has no state where the control-out node can put it's data, I've switched it as \nan example via the webservice-node. See a short video here: https://cloud.codm.de/index.php/s/IttSURIGl8OkUBf\n\n### Caveats\nOnly `controls` and `msInfo` are parsed, no `mediaServer`, `weatherServer`, etc. Is this enough? \n\nEvents can only be generated by control-in and the controls have to be visible to show up in the node. \nWell, this is not a caveat as it lays in the design of Loxone's websocket. \nWe can only come around this if Loxone add's a \"websocket\" checkmark to the controls in Loxone-Config.\nAlso controls will not be shown if you put them in room \"unused\" _and_ category \"unused\", albeit they\nare marked \"visible\".\n\nI've discovered that a switch element emits its current state (`active`) two times with the same value.\nThe first one when the trigger-button is pressed and second one when the button is released - so \ntake care of this as it might give you unexpected results. This could be catched with a delay node.\nAlso keep in mind, that this element sends `1/0` but expects to be fed with `On/Off/Pulse`.\n\n### nodeJS\nI advice you to use the latest [LTS version](https://github.com/nodejs/LTS) of nodeJS.\n\nIf you realy can not update to a supported version of nodeJS, the last version of node-red-contrib-loxone running with \nnodeJS `\u003c 4.5` is `0.4.0` which can be installed with:\n\n    cd ~/.node-red\n    npm install node-red-contrib-loxone@0.4.0\n\n### ToDo \n* Convenience / Testing!\n* better logging, more failsaveness, more user info\n* See `TODO` comments in the code\n* ...\n\n### Installation\nInstall the usual way. Either\n\n    cd ~/.node-red/\n    npm install node-red-contrib-loxone\n    \nor via node-red's `Manage palette`.\n\n### Contributing\n\n1. Fork it!\n2. Create your feature branch: `git checkout -b my-new-feature`\n3. Commit your changes: `git commit -am 'Add some feature'`\n4. Push to the branch: `git push origin my-new-feature`\n5. Submit a pull request :D\n\n### Credits\nPatrik Mayer with great help from [Ladislav Dokulil](https://github.com/alladdin) without whom this could not be possible, 2017 \n\nMany thanks to [Nick O'Leary](https://github.com/knolleary), [Dave Conway-Jones](https://github.com/dceejay/)\n and everyone else from the node-red Slack-Channel. \n\nAlso the people from the ever helpful [LoxForum](https://www.loxforum.com/) have to be mentioned.\n\nI'm not affiliated with [Loxone](https://www.loxone.com/) in any way.\n\n\n### License\nMIT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodmpm%2Fnode-red-contrib-loxone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodmpm%2Fnode-red-contrib-loxone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodmpm%2Fnode-red-contrib-loxone/lists"}