{"id":21838266,"url":"https://github.com/zachfi/iotcontroller","last_synced_at":"2025-10-08T07:31:03.031Z","repository":{"id":73242384,"uuid":"570370140","full_name":"zachfi/iotcontroller","owner":"zachfi","description":"A Kubernetes controller to manage IOT interactions and config","archived":false,"fork":false,"pushed_at":"2025-01-08T00:49:41.000Z","size":15474,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-08T01:28:40.091Z","etag":null,"topics":["grpc","iot","kubernetes","mqtt","zigbee"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zachfi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2022-11-25T02:40:43.000Z","updated_at":"2025-01-08T00:49:42.000Z","dependencies_parsed_at":"2023-10-11T01:09:24.662Z","dependency_job_id":"d4eee0b2-8a65-4255-af93-f01bad51eb6c","html_url":"https://github.com/zachfi/iotcontroller","commit_stats":{"total_commits":25,"total_committers":2,"mean_commits":12.5,"dds":0.48,"last_synced_commit":"875b90209c3888126c0325881e83fa0eed2c478c"},"previous_names":["xaque208/iotcontroller"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zachfi%2Fiotcontroller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zachfi%2Fiotcontroller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zachfi%2Fiotcontroller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zachfi%2Fiotcontroller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zachfi","download_url":"https://codeload.github.com/zachfi/iotcontroller/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235692525,"owners_count":19030678,"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":["grpc","iot","kubernetes","mqtt","zigbee"],"created_at":"2024-11-27T21:09:41.366Z","updated_at":"2025-10-08T07:30:59.490Z","avatar_url":"https://github.com/zachfi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iotcontroller\n\nIOTController is a Kubernetes controller for IOT devices.\n\n## Description\n\n### Harvester\n\nThe harvester reads messages from an MQTT topic and forwards them to the router over gRPC.\n\n### Router\n\nThe router reads the topic to determine which route is capable of parsing the\nmessage and calls the route with the corresponding payload.\n\nTwo message routes are supported currently, though new routes may be added\nquite easily to extend support additional platforms and messages in the future.\n\nA couple future ideas that come to mind are perhaps a Home Assistant route to\nallow compatibility with anything in that ecosystem. Similarly, an ESPHome\nformat could be included so that devices flashed with their firmware could be\nread into this project. I also plan to re-integrate the messages that Anavi\ndevices send, which may be one of the above accidentally.\n\nAs new devices appear on the bus, they are written as `Device` resources in\nKubernetes to include information like their Type and some status information\nabout when the last time the device was seen. These `Device` resources are\ngrouped by the user with `Zone` resources, which inform the Conditioner and\nother components how to operate these devices.\n\n#### Zigbee2Mqtt\n\n[Zigbee2Mqtt](https://www.zigbee2mqtt.io/) is a great open source source\nproject for bridging a Zigbee network with MQTT. This means that instead of\ninterfacing directly with a Zigbee network, all interactions can be done\nthrough an MQTT topic, which this project leverages. Currently, this is the\nprimary use of this tool to controll zigbee lights, switches and metric sensor\ndata.\n\n#### iSpindel\n\nThese messages are sent over WiFi directly to an MQTT topic. The router reads\nthese messages and exports metrics based on their data. The data format here\nis pretty simple and is used to track the progress of home brew cider\nfermentations.\n\n### Conditioner\n\nThe Conditioner's responsibility is to allow users to express `Condition` type\nresources to express the desired handling when certain events are received.\nThese events come from both the HookReceiver and Weather modules. The events\nhave a name and a set of labels. Thees labels are used to match against the\n`Condition` resources to determine what the appropriate action for the zone is.\nThe Conditioner then calls the ZoneKeeper to apply the change.\n\n### Controller\n\nThis project was built using `kubebuilder`. The Controller here is the main\nKubernetes controller, but moved into the module structure this project uses.\nPrimarily it is used to create the caching client used to interface with\nKubernets for the various components. This Client is a dependency of several\nother modules. Bother Zone and Device reconcilers exist for syncing labels and\nlinking of resource types for zone ownership over devices.\n\n### Hook Receiver\n\nThe HookReceiver exposes an HTTP endpoint compatible with the Alertmanager web hook payload. This allows the configuration of alerts in alert manager and forward to the controller to determine if action on a zone is required. For example, if a low temperature alert is fired, a `Condition` resource can match the associated labels and turn on a Zigbee switch to turn on a heater. The event labels are read from the alert. This allows for some programming; using events to apply states to zones for remediation. Additionally, an inactive state cane be added to these `Condition` resources so that when the alert sends a \"resolved\" status, the condition can be set back to its original state.\n\n### Weather\n\nThis module reads data from Open Weather Map based on coordinates. Metrics for the various weather events are exported on a Prometheus endpoint, for alerting and graphing purposes. Additionally \"epoch\" events are sent to the conditioner directly for \"sunset\" and \"sunrise\" events so that conditions can express a desire to handle for these events.\n\n### Zone Keeper\n\nZoneKeeper is the actual enforcement of state on a zone. It keeps state of all\ndesires on all zones, and which devices of which type and how to handle those\nactions. This module has no opinions of its own, and only enforces what the\nConditioner tells it to enforce.\n\n## Getting Started\n\nYou’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.\n**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).\n\n### Running on the cluster\n\n1. Install Instances of Custom Resources:\n\n```sh\nkubectl apply -f config/samples/\n```\n\n2. Build and push your image to the location specified by `IMG`:\n\n```sh\nmake docker-build docker-push IMG=\u003csome-registry\u003e/iotcontroller:tag\n```\n\n3. Deploy the controller to the cluster with the image specified by `IMG`:\n\n```sh\nmake deploy IMG=\u003csome-registry\u003e/iotcontroller:tag\n```\n\n### Uninstall CRDs\n\nTo delete the CRDs from the cluster:\n\n```sh\nmake uninstall\n```\n\n### Undeploy controller\n\nUnDeploy the controller to the cluster:\n\n```sh\nmake undeploy\n```\n\n## Contributing\n\n// TODO(user): Add detailed information on how you would like others to contribute to this project\n\n### How it works\n\nThis project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)\n\nIt uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)\nwhich provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster\n\n### Test It Out\n\n1. Install the CRDs into the cluster:\n\n```sh\nmake install\n```\n\n2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):\n\n```sh\nmake run\n```\n\n**NOTE:** You can also run this in one step by running: `make install run`\n\n### Modifying the API definitions\n\nIf you are editing the API definitions, generate the manifests such as CRs or CRDs using:\n\n```sh\nmake manifests\n```\n\n**NOTE:** Run `make --help` for more information on all potential `make` targets\n\nMore information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)\n\n## License\n\nCopyright 2022.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzachfi%2Fiotcontroller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzachfi%2Fiotcontroller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzachfi%2Fiotcontroller/lists"}