{"id":20485490,"url":"https://github.com/homieiot/convention","last_synced_at":"2026-01-12T03:00:59.055Z","repository":{"id":46074587,"uuid":"45796054","full_name":"homieiot/convention","owner":"homieiot","description":"🏡 The Homie Convention: a lightweight MQTT convention for the IoT","archived":false,"fork":false,"pushed_at":"2025-12-28T19:37:43.000Z","size":250,"stargazers_count":740,"open_issues_count":25,"forks_count":62,"subscribers_count":53,"default_branch":"develop","last_synced_at":"2025-12-31T11:02:08.638Z","etag":null,"topics":["convention","home-automation","homie","iot","mqtt"],"latest_commit_sha":null,"homepage":"https://homieiot.github.io/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/homieiot.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-11-08T19:49:28.000Z","updated_at":"2025-12-28T19:37:47.000Z","dependencies_parsed_at":"2023-02-14T15:46:45.545Z","dependency_job_id":"0b581097-b604-4a52-9948-79ce9038ab12","html_url":"https://github.com/homieiot/convention","commit_stats":{"total_commits":204,"total_committers":30,"mean_commits":6.8,"dds":0.7009803921568627,"last_synced_commit":"f029eca255b6148f37097d16b5323e7e41a8372e"},"previous_names":["marvinroger/homie"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/homieiot/convention","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homieiot%2Fconvention","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homieiot%2Fconvention/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homieiot%2Fconvention/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homieiot%2Fconvention/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/homieiot","download_url":"https://codeload.github.com/homieiot/convention/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homieiot%2Fconvention/sbom","scorecard":{"id":468344,"data":{"date":"2025-08-11","repo":{"name":"github.com/homieiot/convention","commit":"de48bf4f89fe1113d9d75f5196d454f446dc6699"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.8,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":10,"reason":"all changesets reviewed","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/trigger_website.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: third-party GitHubAction not pinned by hash: .github/workflows/trigger_website.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/homieiot/convention/trigger_website.yml/develop?enable=pin","Info:   0 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE.md:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-19T13:06:35.155Z","repository_id":46074587,"created_at":"2025-08-19T13:06:35.155Z","updated_at":"2025-08-19T13:06:35.155Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28332831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"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":["convention","home-automation","homie","iot","mqtt"],"created_at":"2024-11-15T16:31:08.161Z","updated_at":"2026-01-12T03:00:58.896Z","avatar_url":"https://github.com/homieiot.png","language":null,"funding_links":[],"categories":["Architecture, Convention"],"sub_categories":["Misc"],"readme":"\u003ch1 align=\"center\"\u003e\u003ca href=\"https://homieiot.github.io\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/homieiot/convention-website/master/static/img/Homie-logo.svg\" height=\"200\"\u003e\u003cbr\u003eThe Homie Convention\u003c/a\u003e\u003c/h1\u003e\n\u003ci align=\"center\"\u003eA lightweight MQTT convention for the IoT\u003c/i\u003e\n\n## Motivation\n\nThe Homie convention strives to be a messageing convention that makes it easy to interconnect IoT devices. In such a way that devices will not need to know anything about other devices internal implementations, hardware, or connectivity.\n\nThe Homie convention is a **communication definition on top of MQTT** between IoT devices and controlling entities.\n\n\u003e [MQTT](http://mqtt.org) is a machine-to-machine (M2M)/\"Internet of Things\" connectivity protocol.\n\u003e It was designed as an extremely lightweight publish/subscribe messaging transport.\n\nMQTT supports easy and unrestricted message-based communication.\nHowever, MQTT doesn't define the structure and content of these messages and their relation.\nAn IoT device publishes data and provides interaction possibilities but a controlling entity will need to be specifically configured to be able to interface with the device.\n\nThe Homie convention defines a **standardized way** of how IoT devices and services announce themselves and their data on the communication channel.\nThe Homie convention is thereby a crucial aspect in the support of **automatic discovery, configuration and usage** of devices and services over the MQTT protocol.\n\nFind the convention here: https://homieiot.github.io\n\n---\n\n## Guiding design principles\n\nThese principles should be taken into account when proposing changes to the conventuion.\n\n### Separation of concerns\nMany of todays HA applications, both commercial and free, take the approach of an all-in-one package (monolith). This creates closed eco systems and a duplication of work. The biggest challeng in IoT is connecting devices by writing driver-software to integrate them (because of the ever growing number of connected devices available). Each of the available monolithical HA applications duplicates this effort because of their integrated, tightly-coupled designs.\n\nThe Homie based stack consists of multiple layers and components;\n* MQTT as the central communications bus\n* Homie as a MQTT-topic convention to discover and interact with devices and controllers in a standardized way without knowing the device specifics\n* Each device presents itself on this network, according to a well specified format\n\nThis provides a way to only write device interfaces/drivers once, whilst at the same time allows for app developers to build competing apps without having to do the entire infrastructure as well. Which will provide more choice for the users in how they interact with the system.\n\n### Message bus \nUse an industry standard communications bus, no home grown protocols; MQTT.\nThere are many implementations available both free and commercial. \n\n### Easy for users\nIt should have a low entry barrier to use. The only central component required is an MQTT server. So set up an MQTT server, connect a device and a controller application and start controlling your devices\n\n### Easy for developers\nIt should have a low entry barrier for developers. Set up an MQTT server and grab a Homie library and start coding.\n\n### Resource constraints\nDevices with very limited resources should still be able to use the Homie Convention (provided they are MQTT capable).\nControllers are assumed to have more resources available, to be able to build multiple device representations and control many devices simultaneously.\n\n### No control logic\nHomie does specify control logic for devices. It specifies the means by wich other devices or controllers can interact but does not have any logic by itself. Logic engines (if-this then-that) are separate and can be build on top of the convention.\n\n### No GUI type specifications\nHomie does not specify how a GUI should present a device. At most it provides metadata in the device/service descriptions for display etc. GUI's are seperate implementations and can be build on top of the convention.\nThe convention is considerate to specify devices descriptions in a way that will provide hints to a GUI \nSee also [device state](#device-state) below\n\n### Debugging and troubleshooting\nIt should be easy to debug applications, and get feedback from users what is happening in case of problems/support. This is implemented with simple basic types, transmitted in plain text over the MQTT topics.\n\n---\n\n## Device design\n\nSome guidelines for designing Homie device interfaces\n\n\n### Eventual consistency\nAn MQTT bus does not guarantee the order of delivery of messages. This might cause messages to arrive in an order that might be considered invalid. This is an eventual consistency problem, since over time, after all messages have been received, the state should be consistent again. Developers should take this into account.\n\n### Device state\nThe Homie convention allows devices to specify an unambiguous state. This is not necessarily the same state as would be present in a GUI.\n\nThe typical example would be a dimmable light. In a GUI this is often represented as switch (on/off) and a slider (0-100%). Consider the brigtness to be at 0%, and then the user switches the light on. What will now happen? this is an example of an ambiguous state. To make it unambiguous the slider should be designed as 1-100%, taking out the 0% option, since that is perceived as \"off\".\n\nSo the Homie device can use the on/off and 1-100% settings to be unambiguous. However a GUI can choose how it maps those values and settings to a user interface.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomieiot%2Fconvention","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhomieiot%2Fconvention","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomieiot%2Fconvention/lists"}