{"id":24912437,"url":"https://github.com/nerivec/zigbee-on-host","last_synced_at":"2025-10-18T14:00:01.975Z","repository":{"id":272989685,"uuid":"918247995","full_name":"Nerivec/zigbee-on-host","owner":"Nerivec","description":"Open Source ZigBee stack designed to run on a host and communicate with a radio co-processor (RCP)","archived":false,"fork":false,"pushed_at":"2025-01-22T14:45:57.000Z","size":173,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-26T13:56:42.100Z","etag":null,"topics":["host","radio-co-processor","rcp","stack","zigbee","zigbee-rcp","zigbee-stack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nerivec.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2025-01-17T14:47:18.000Z","updated_at":"2025-01-23T08:52:35.000Z","dependencies_parsed_at":"2025-01-17T22:20:04.099Z","dependency_job_id":null,"html_url":"https://github.com/Nerivec/zigbee-on-host","commit_stats":null,"previous_names":["nerivec/zigbee-on-host"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nerivec%2Fzigbee-on-host","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nerivec%2Fzigbee-on-host/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nerivec%2Fzigbee-on-host/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nerivec%2Fzigbee-on-host/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nerivec","download_url":"https://codeload.github.com/Nerivec/zigbee-on-host/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236753359,"owners_count":19199428,"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":["host","radio-co-processor","rcp","stack","zigbee","zigbee-rcp","zigbee-stack"],"created_at":"2025-02-02T05:19:53.107Z","updated_at":"2025-10-16T23:31:17.417Z","avatar_url":"https://github.com/Nerivec.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZigBee on Host\n\n[![Version](https://img.shields.io/npm/v/zigbee-on-host.svg)](https://npmjs.org/package/zigbee-on-host)\n[![CI](https://github.com/Nerivec/zigbee-on-host/actions/workflows/ci.yaml/badge.svg)](https://github.com/Nerivec/zigbee-on-host/actions/workflows/ci.yaml)\n[![CodeQL](https://github.com/Nerivec/zigbee-on-host/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/Nerivec/zigbee-on-host/actions/workflows/github-code-scanning/codeql)\n\nOpen Source ZigBee stack designed to run on a host and communicate with a radio co-processor (RCP).\n\nCurrent implementation aims for compatibility with OpenThread RCP firmware. That base provides compatibility with any chip manufacturer that supports it (Silabs, TI, etc.) with the only requirements being proper implementation of the `STREAM_RAW` mechanism of the `Spinel` protocol (which allows to send raw 802.15.4 frames, including... ZigBee!) and hardware MAC ACKing.\n\n_This library can also serve as a base for pentesting ZigBee networks thanks to the ability to easily craft various payloads at any layer of the specification and send them through the raw stream using any network parameters._\n\n\u003e [!IMPORTANT]\n\u003e Work in progress! Expect breaking changes without backwards compatibility for a while!\n\n## Development\n\n[CONTRIBUTING](./CONTRIBUTING.md)\n\n### Current status\n\n\u003e [~] Partial feature, [?] Uncertain feature\n\n- [x] Encoding/decoding of Spinel \u0026 HDLC protocols\n- [x] Encoding/decoding of MAC frames\n- [x] Encoding/decoding of ZigBee NWK frames\n  - [ ] Lacking reference sniffs for multicast (group)\n- [x] Encoding/decoding of ZigBee NWK GP frames\n- [x] Encoding/decoding of ZigBee NWK APS frames\n- [x] Network forming\n- [x] Network state saving (de facto backups)\n- [x] Network state reset\n- [x] Joining/Rejoining\n  - [x] APS TC link key update mechanism (global)\n  - [x] Direct child router\n  - [x] Direct child end device\n  - [x] Nested device\n- [x] Indirect transmission mechanism\n- [x] Source routing\n- [ ] Route repairing\n- [x] Coordinator LQI/Routing tables (for network map data on coordinator side)\n- [x] LQI reporting\n  - [ ] Refining\n- [ ] Install codes\n- [?] APS APP link keys\n- [ ] InterPAN / Touchlink\n- [ ] R23 (need reference sniffs...)\n- [~] Security\n- [ ] Metrics/Statistics\n- [ ] Big cleanup of unused / never will use!\n\nAnd likely more, and of course a bunch of `TODO`s in the code!\n\nYou can also contribute by submitting sniffs/captures. [More information here](https://github.com/Nerivec/zigbee-on-host/discussions/14).\n\n### OpenThread RCP firmware notes\n\n- [Texas Instruments] Does not currently implement `PHY_CCA_THRESHOLD` (cannot read or write value)\n\n## Testing\n\n#### Current Status\n\n- CI: ~70% coverage\n- Stress-testing: pending\n- Firmware stability:\n  - Silicon Labs: ongoing\n  - Texas Instruments: ongoing\n  - Nordic Semiconductor: [pending](https://github.com/Nerivec/zigbee-on-host/discussions/18)\n- Usage in test networks: ongoing\n- Usage in live networks: pending\n\n### Firmware\n\nUse the appropriate OpenThread RCP firmware for your adapter:\n- Silicon Labs: https://github.com/Nerivec/silabs-firmware-builder/releases\n- Texas Instruments: https://github.com/Koenkk/OpenThread-TexasInstruments-firmware/releases\n- Nordic Semiconductor: https://github.com/Nerivec/zigbee-on-host/discussions/18\n\n### Zigbee2MQTT\n\nZigbee2MQTT 2.1.3-dev (after [PR #26742](https://github.com/Koenkk/zigbee2mqtt/pull/26742)) and later versions should allow the use of the `zoh` adapter.\nMake sure you followed the above steps to get the proper firmware, then configure your `configuration.yaml`, including:\n\n\u003e [!TIP]\n\u003e It is currently recommended you use Zigbee2MQTT `latest-dev` (`edge`) to get the latest fixes when testing this implementation!\n\n```yaml\nserial:\n  port: /dev/serial/by-id/my-device-id-here\n  adapter: zoh\n  # unused for TCP-based coordinator\n  baudrate: 460800\n  # as appropriate for your coordinator/firmware, unused for TCP-based coordinator\n  rtscts: true\n```\n\n\u003e [!TIP]\n\u003e ZigBee on Host saves the current state of the network in the file `zoh.save`. _It is similar to the NVRAM of an NCP coordinator._\n\u003e This file contains everything needed to re-establish the network on start, hence, a `coordinator_backup.json` is never created by Zigbee2MQTT. It is located alongside the `database.db` in the `data` folder.\n\n\u003e [!TIP]\n\u003e The EUI64 (IEEE address) in the firmware of the coordinator is ignored in this mode. A static one is used instead (set by Zigbee2MQTT), allowing you to change coordinators at will on the same network (although you may encounter device-related troubles when radio specs vary wildly).\n\n### CLI \u0026 Utils\n\nClone the repository.\n\n```bash\ngit clone https://github.com/Nerivec/zigbee-on-host\ncd zigbee-on-host\n```\n\nInstall dev dependencies and build:\n\n```bash\nnpm ci\nnpm run build\n```\n\n\u003e [!IMPORTANT]\n\u003e Running `npm run build:prod` omits the `src/dev` directory (for production). If you do, you will not be able to use `dev:*` commands.\n\n\u003e [!TIP]\n\u003e If having issues with building, try removing the `*.tsbuildinfo` incremental compilation files (or run `npm run clean` first).\n\n#### Utils\n\n##### Create a 'zoh.save' from the content of a Zigbee2MQTT data folder\n\n```bash\nnpm run dev:z2z ./path/to/data/\n```\n\n\u003e [!TIP]\n\u003e This allows you to quickly take over a network created with `zstack` or `ember`. You then just need to change the `configuration.yaml` to `adapter: zoh` and `baudrate: 460800` (and `port` as appropriate).\n\n##### Print and save the content of the 'zoh.save' in the given directory in human-readable format (as JSON, in same directory)\n\n```bash\nnpm run dev:z2r ./path/to/data/\n```\n\n##### CLI\n\nGet a list of supported commands with:\n\n```bash\nnpm run dev:cli help\n```\n\n\u003e [!TIP]\n\u003e `dev:cli` commands can be configured in more details using the file `dist/dev/conf.json`. Some environment variables are also available to quickly configure the adapter \u0026 wireshark. _The effective config is printed at the start of every command (`help` included)._\n\n##### Using Docker\n\n###### Prerequisites\n\n```bash\ngit clone https://github.com/Nerivec/zigbee-on-host\ncd zigbee-on-host\ndocker compose -f docker-dev/compose.yaml up -d --pull never\ndocker compose -f docker-dev/compose.yaml exec zigbee-on-host npm ci\ndocker compose -f docker-dev/compose.yaml exec zigbee-on-host npm run build\n```\n\n###### Running util commands\n\nCreate 'zoh.save' (details above):\n\n```bash\ndocker compose -f docker-dev/compose.yaml exec zigbee-on-host npm run dev:z2z ./path/to/data\n```\n\nPrint readable 'zoh.save' content (details above):\n\n```bash\ndocker compose -f docker-dev/compose.yaml exec zigbee-on-host npm run dev:z2r ./path/to/data\n```\n\nCLI:\n\n```bash\ndocker compose -f docker-dev/compose.yaml exec zigbee-on-host npm run dev:cli help\n```\n\n\u003e [!TIP]\n\u003e `dev:cli` commands can be configured in more details using the file `dist/dev/conf.json`. Some environment variables are also available to configure the adapter \u0026 wireshark from the compose file. _The effective config is printed at the start of every command (`help` included)._\n\n###### Stopping \u0026 removing the container\n\n```bash\ndocker compose -f docker-dev/compose.yaml down\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerivec%2Fzigbee-on-host","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnerivec%2Fzigbee-on-host","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerivec%2Fzigbee-on-host/lists"}