{"id":21442193,"url":"https://github.com/hwhw/zigbee-lua","last_synced_at":"2025-07-19T20:07:27.687Z","repository":{"id":45960244,"uuid":"158079108","full_name":"hwhw/zigbee-lua","owner":"hwhw","description":"Zigbee coordinator and tools for LuaJIT","archived":false,"fork":false,"pushed_at":"2021-04-11T15:48:40.000Z","size":199,"stargazers_count":26,"open_issues_count":1,"forks_count":5,"subscribers_count":10,"default_branch":"master","last_synced_at":"2023-03-12T07:33:11.173Z","etag":null,"topics":["cc-znp","cc2530","cc2531","etrx3","lua","luajit","mqtt","zcl","zigbee"],"latest_commit_sha":null,"homepage":null,"language":"Lua","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/hwhw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.TXT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-18T11:59:54.000Z","updated_at":"2022-05-23T14:56:58.000Z","dependencies_parsed_at":"2022-08-23T21:20:40.092Z","dependency_job_id":null,"html_url":"https://github.com/hwhw/zigbee-lua","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwhw%2Fzigbee-lua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwhw%2Fzigbee-lua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwhw%2Fzigbee-lua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hwhw%2Fzigbee-lua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hwhw","download_url":"https://codeload.github.com/hwhw/zigbee-lua/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225990479,"owners_count":17556153,"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":["cc-znp","cc2530","cc2531","etrx3","lua","luajit","mqtt","zcl","zigbee"],"created_at":"2024-11-23T01:52:56.546Z","updated_at":"2024-11-23T01:52:57.001Z","avatar_url":"https://github.com/hwhw.png","language":"Lua","readme":"## Zigbee-lua\n\nA Zigbee control framework written in Lua.\n\n### Requirements\n\n* [LuaJIT](https://luajit.org/) (uses ffi, bitop)\n* [libmicrohttpd](https://www.gnu.org/software/libmicrohttpd/)\n* [mosquitto](https://mosquitto.org/)\n\n### Supported devices\n\nStatus: It's operational. You can use this to run a Zigbee coordinator and\ncontrol its communication. Via the TCP interface, you can control its behaviour\nand e.g. send adhoc custom packages. Best results are currently archieved\nusing a CC2538 device. CC2530/31 are working, too - they have difficulties\ndealing with larger networks due to their extremely limited CPU and memory\nresources, though.\n\nControllers:\n\n* **CC253x** via ZNP. Status: CC253x: testing is done using the CC253x firmware\nfrom zigbee2mqtt project.\n* **ETRX3** series (probably broken ATM). Status: interfacing using the AT\ncommand set, tested with firmware R309, possibly broken at the moment until\nlatest set of changes are implemented.\n\nDevices:\n\n* TBD\n\n### Features:\n\n* start up a Zigbee coordinator\n* maintain a simple device database\n* TCP interface for injecting code into the running instance\n* MQTT client that allows for publishing/subscribing (still rough around\n  the edges, see `mqtt-environment.lua` for a very basic example)\n* HTTP server via libmicrohttpd\n* ZCL abstraction to build/parse data packages\n* ZLL touchlink factory reset (implemented on CC253x for now, still problems\n  with sweeping over many channels - but working successfully for my Hue\n  lightbulbs)\n\n\n### Description of software structure\n\n* Core (in lib/):\n  * `ctx.lua` is a general application context. It is supposed to be the\n    single instance of its kind. It implements:\n    * coroutine based tasks integrated with\n    * messaging between these tasks\n  * `util.lua` is a collection of small utility functions, e.g. logging, table\n    copies and more\n  * `srv-epoll.lua` is a epoll-based (and thus: Linux specific) wrapper around\n    socket management. This would have to be reimplemented on other platforms.\n    It also implements a main loop which is used from `ctx.lua`.\n  * `serial.lua` is a ljsyscall based wrapper for serial/UART communication\n  * `codec.lua` is a generic binary protocol codec, configured by simple Lua\n    data structures.\n\n* Interfaces (in interfaces/):\n  * These will get loaded depending on configuration (in `config.lua`, or whatever\n    you include in its place)\n  * Noteworthy interface is the \"zigbee\" interface. There is a try to separate\n    the protocol stuff (`interfaces/zigbee.lua`, `interfaces/zigbee/zcl.lua`)\n    from device-/cluster-specific code\n  * The CC253x ZNP interface is in `interfaces/zigbee/devices/dongle-cc253x.lua`,\n    the ZNP protocol definition (using `codec.lua`) can be found in\n    `interfaces/zigbee/cc-znp.lua`\n  * The ETRX3 interface is in `interfaces/zigbee/devices/dongle-etrx3.lua`\n\n\n### Usage\n\nThe following description assumes that you want to use this software to build\na home automation infrastructure with Zigbee devices - which is what drove the\ndevelopment of this software in the first place. But note that you can probably\nuse this software for other tasks, too.\n\n1. Prepare software\n  * check out the git submodules. You do not need luarocks or similar lua\n    package management. Just do:\n    ```\n    $ git submodule init\n    $ git submodule update\n    ```\n2. Prepare hardware\n  * CC253x: flash with appropriate firmware. See firmware remarks for a very\n    subjective view on what you should use.\n  * ETRX3 based hardware: should already have firmware\n3. optional: configure USB serial interface permissions\n   This might be your chance to look and see what udev is and can do for you\n4. edit/adapt `config.lua` or integrate it into your own \"environment\" definition\n5. Run an \"environment\" that will itself call out to `lib/ctx.lua`\n\nThen:\n\n* peruse scripts in contrib/ to show list of known devices, permit network\n  joins, name devices, ...\n* create an \"environment\" by writing event handling functions that trigger\n  actions. Have a look at the example environments in the project's root\n  directory.\n\n\n### Similar projects:\n\nWhen I started this whole smarthome project of mine, I had a loooong look at\nhttps://github.com/Koenkk/zigbee2mqtt - and I used it for a short amount of\ntime. It is good for what it does. I have to admit though, that I have a\ncertain dislike for Javascript in general and the nodejs ecosystem in\nparticular. Zigbee2mqtt pulled LOTS of other packages and there is no way\nto get me motivated enough to go and see what they all do. Yes, there is\nsome amount of \"not invented here\" syndrome, too. Zigbee2mqtt mostly stands on\nthe shoulders of https://github.com/zigbeer/zigbee-shepherd.\n\nI was not really content with the behaviour of these applications. A lot of\ndevelopment seems to be on the \"hacky\" side, which is generally fine. However,\nthese levels of hacks are accumulating...\n\nAlso, I found some really nicely written software:\n\nhttps://github.com/Frans-Willem/AqaraHub/ is really nicely abstracted, very\nconcise modern C++. ZNP and ZCL are cleanly abstracted. Its abstractions use\nfutures, which makes for easily read state machines - a value in its own\naccord for a state machine heavy task. This software, like Zigbee2mqtt,\nfocuses on providing an MQTT interface for controlling the Zigbee devices.\n\nhttps://github.com/Tropicao/zigbridge/ is also really nicely abstracted.\nIt is written in a very nicely styled C, from the enlightenment.org school\nof programming. It does NOT provide an MQTT interface and has some rudimentary\nimplementation of other interfaces.\n\nMaking up my mind, I came to the point where I wanted to have my own\nimplementation. Central design points were:\n\n* not focused on MQTT only (or even at all?)\n* must allow to script the \"home automation\" logic\n* must allow for access to as many Zigbee (ZDP/ZCL) features as possible\n* must not try to be too clever\n\nWhile Languages like C++ and C have their appeal (and I spent a few days\nthinking about continuing development by reusing corresponding projects),\nI am quite proficient with Lua and Lua/C interop using (LuaJIT) FFI. So\nI settled on this. Result is a very compact (in terms of lines of code)\ncore that allows quite some flexibility.\n\n\n### Roadmap:\n\n* Something to store/analyze sensor data (temperature \u0026 so on)\n* Better abstracted Zigbee device classes (rather than the \"any.lua\" which\n  does a bit of everything)\n* Better examples\n* Tests\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhwhw%2Fzigbee-lua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhwhw%2Fzigbee-lua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhwhw%2Fzigbee-lua/lists"}