{"id":15797296,"url":"https://github.com/microclimates/homie-device","last_synced_at":"2025-05-12T14:12:43.611Z","repository":{"id":57266415,"uuid":"101932207","full_name":"microclimates/homie-device","owner":"microclimates","description":"NodeJS port of Homie for IoT ","archived":false,"fork":false,"pushed_at":"2019-07-12T17:04:03.000Z","size":57,"stargazers_count":20,"open_issues_count":2,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-12T14:12:30.419Z","etag":null,"topics":["homie","homie-convention","homie-devices","homie-esp8266","iot","mqtt","mqtt-client","nodejs","raspberry-pi"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/microclimates.png","metadata":{"files":{"readme":"README.md","changelog":"History.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-30T21:51:26.000Z","updated_at":"2022-10-06T09:26:20.000Z","dependencies_parsed_at":"2022-08-25T03:41:05.455Z","dependency_job_id":null,"html_url":"https://github.com/microclimates/homie-device","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microclimates%2Fhomie-device","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microclimates%2Fhomie-device/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microclimates%2Fhomie-device/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microclimates%2Fhomie-device/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microclimates","download_url":"https://codeload.github.com/microclimates/homie-device/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253754220,"owners_count":21958842,"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":["homie","homie-convention","homie-devices","homie-esp8266","iot","mqtt","mqtt-client","nodejs","raspberry-pi"],"created_at":"2024-10-05T00:06:21.936Z","updated_at":"2025-05-12T14:12:43.587Z","avatar_url":"https://github.com/microclimates.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Homie Device\n============\n\n[![NPM](https://nodei.co/npm/homie-device.svg?downloads=true\u0026downloadRank=true)](https://nodei.co/npm/homie-device/)\u0026nbsp;\u0026nbsp;\n[![Build Status](https://secure.travis-ci.org/microclimates/homie-device.svg?branch=master)](https://travis-ci.org/microclimates/homie-device)\u0026nbsp;\u0026nbsp;\n[release notes](https://github.com/microclimates/homie-device/blob/master/History.md)\n\nThis is a NodeJS port of the [Homie convention](https://github.com/marvinroger/homie) for lightweight IoT device interaction on an [MQTT](https://en.wikipedia.org/wiki/MQTT) message bus.\n\nIt is modeled after the great work done for [ESP8266 devices](https://github.com/marvinroger/homie-esp8266), with the goal of not only following the Homie Convention, but at adhering to the implementation interface so both message and API interfaces are familiar.\n\nIt's great for mixing ESP8266 devices with Raspberry Pi and other linux or windows based systems on the same MQTT network.\n\nFeatures\n--------\n\n* Device, Node, and Property with ESP8266-like interface\n* Auto MQTT connect with optional username/password\n* Auto MQTT re-connect\n* Device config matching ESP8266 config JSON\n* Periodic $stats/uptime publishing\n* $online will\n* Device topic events\n* Broadcast message events\n* Periodic stats interval events\n* Device/node/property announcement on connect\n* Property send with retained value\n* Settable properties\n* Property ranges\n* Lightweight\n* Full test coverage\n\nQuick Start\n-----------\n\nFirst, get a local [MQTT broker](https://mosquitto.org/download/) running and a window opened subscribing to the 'devices/#' topic.\n\nNext, add these lines to an index.js file and run it:\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('bare-minimum');\nmyDevice.setup();\n```\n\nCongratulations, you've got a running Homie device! \n\nTake a look at the messages on your MQTT bus under devices/bare-minimum. Then ctrl-c the program and watch the broker administer the will.\n\nSetting Firmware\n----------------\n\nTo publish the firmware name \u0026 version, call `myDevice.setFirmware()`:\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('bare-minimum');\nmyDevice.setFirmware('nodejs-test', '0.0.1');\nmyDevice.setup();\n```\n\nAdding a Node\n-------------\n\nDevices aren't much use until they have some nodes and properties. Place the following into the index.js file and run it again:\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('my-device');\nvar myNode = myDevice.node('my-node', 'test node friendly name', 'test-node');\nmyNode.advertise('my-property-1').setName('Friendly Prop Name').setUnit('W').setDatatype('integer');\nmyDevice.setup();\n```\n\nPublishing a Property\n---------------------\n\nPublishing properties has the same interface as the Homie ESP8266 implementation:\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('my-device');\nvar myNode = myDevice.node('my-node', 'test node friendly name', 'test-node');\nmyNode.advertise('my-property-1').setName('Friendly Prop Name').setUnit('W').setDatatype('integer');\nmyDevice.setup();\n\nmyNode.setProperty('my-property-1').send('property-value');\n```\n\nSettable Properties\n-------------------\n\nTo set properties from MQTT messages, add a setter function when advertising the property:\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('my-device');\nvar myNode = myDevice.node('my-node', 'test node friendly name', 'test-node');\nmyNode.advertise('my-property-1').setName('Friendly Prop Name').setUnit('W').setDatatype('string').settable(function(range, value) {\n  myNode.setProperty('my-property-1').setRetained().send(value);\n});\nmyDevice.setup();\n```\n\nOnce running, publish a message to the `devices/my-device/my-node/my-property-1/set` topic.\n\nArray Nodes\n----------------\n\nArray nodes are also supported by passing lower and upper bounds on the range when creating the node.\n\n```\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('my-device');\n\nvar lowerBound = 0;\nvar upperBound = 10;\nvar myNode = myDevice.node('my-node', 'test node friendly name', 'test-node', lowerBound, upperBound);\n```\n\nPublishing a property to a specific node index can be done like this:\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('my-device');\nvar myNode = myDevice.node('my-node', 'test node friendly name', 'test-node', 0, 10);\nmyNode.advertise('my-property-1');\nmyDevice.setup();\n\n// Publishes 'property-value' to the 'devices/my-device/my-node_2/my-property-1' topic.\nmyNode.setProperty('my-property-1').setRange(2).send('property-value');\n```\n\nSetting a property on a specific node index can be done like this:\n\n```\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('my-device');\nvar myNode = myDevice.node('my-node', 'test node friendly name', 'test-node', 0, 10);\nmyNode.advertise('my-property-2').settable(function(range, value) {\n  var index = range.index;\n  myNode.setProperty('my-property-2').setRange(index).send(value);\n});\nmyDevice.setup();\n```\n\nNow publish a message to the `devices/my-device/my-node_8/my-property-2/set` topic.\n\nDevice Messages\n---------------\n\nIncoming messages to the device emit `message` events. You can listen for all messages to the `devices/my-device/#` topic like this:\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('my-device');\n\nmyDevice.on('message', function(topic, value) {\n  console.log('A message arrived on topic: ' + topic + ' with value: ' + value);\n});\n\nmyDevice.setup();\n```\n\nNow publish a message to the `devices/my-device/my-node/my-property-2_8/set` topic.\n\nTopic Messages\n--------------\n\nYou can listen for specific incoming topics by adding a listener to the `message:{topic}` event for the device:\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('my-device');\n\nmyDevice.on('message:my/topic', function(value) {\n  console.log('A message arrived on the my/topic topic with value: ' + value);\n});\n\nmyDevice.setup();\n```\n\nNow publish a message to the `devices/my-device/my/topic` topic.\n\nBroadcast Messages\n------------------\n\nYou can listen to all `devices/$broadcast/#` messages by adding a listener to the `broadcast` event:\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('my-device');\n\nmyDevice.on('broadcast', function(topic, value) {\n  console.log('A broadcast message arrived on topic: ' + topic + ' with value: ' + value);\n});\n\nmyDevice.setup();\n```\n\nNow publish a broadcast message to the `devices/$broadcast/some-topic` topic. All homie devices are exposed to broadcast messages.\n\nDevice Settings\n---------------\n\nTo configure your device with external settings, pass a full or partial config object to the HomieDevice constructor. If you've worked with the Homie ESP8266 implementation, this will be familiar:\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar config = {\n  \"name\": \"Bare Minimum\",\n  \"device_id\": \"bare-minimum\",\n  \"mqtt\": {\n    \"host\": \"localhost\",\n    \"port\": 1883,\n    \"base_topic\": \"devices/\",\n    \"auth\": false,\n    \"username\": \"user\",\n    \"password\": \"pass\"\n  },\n  \"settings\": {\n    \"percentage\": 55\n  }\n}\nvar myDevice = new HomieDevice(config);\nmyDevice.setup();\n```\n\nConnection\n----------\n\nThe Homie device maintains an `isConnected` (true/false) state, and emits \na `connect` and `disconnect` event as the device becomes connected with MQTT.\n\nQuiet Setup\n-----------\n\nIf you don't want the startup message, pass the quiet flag of `true` to setup `myDevice.setup(true)`.\n\n```javascript\nvar HomieDevice = require('homie-device');\nvar myDevice = new HomieDevice('bare-minimum');\nmyDevice.setup(true);\n```\n\nContributors\n------------\n\u003ctable id=\"contributors\"\u003e\u003ctr\u003e\n\u003ctd\u003e\u003cimg width=\"124\" src=\"https://avatars2.githubusercontent.com/u/373538?v=4\"\u003e\u003cbr/\u003e\u003ca href=\"https://github.com/lorenwest\"\u003elorenwest\u003c/a\u003e\u003c/td\u003e\u003ctd\u003e\u003cimg width=\"124\" src=\"https://avatars0.githubusercontent.com/u/7427179?v=4\"\u003e\u003cbr/\u003e\u003ca href=\"https://github.com/marcus-garvey\"\u003emarcus-garvey\u003c/a\u003e\u003c/td\u003e\u003ctd\u003e\u003cimg width=\"124\" src=\"https://avatars0.githubusercontent.com/u/7627635?v=4\"\u003e\u003cbr/\u003e\u003ca href=\"https://github.com/rozpuszczalny\"\u003erozpuszczalny\u003c/a\u003e\u003c/td\u003e\u003ctd\u003e\u003cimg width=\"124\" src=\"https://avatars1.githubusercontent.com/u/5964259?s=460\u0026v=4\"\u003e\u003cbr/\u003e\u003ca href=\"https://github.com/carterzenk\"\u003ecarterzenk\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\nLicense\n-------\n\nMay be freely distributed under the [MIT license](https://raw.githubusercontent.com/microclimates/homie-device/master/LICENSE).\n\nCopyright (c) 2017-2018 Loren West \n[and other contributors](https://github.com/microclimates/homie-device/graphs/contributors)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicroclimates%2Fhomie-device","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicroclimates%2Fhomie-device","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicroclimates%2Fhomie-device/lists"}