{"id":13710685,"url":"https://github.com/shimmeringbee/zstack","last_synced_at":"2025-05-06T19:32:27.939Z","repository":{"id":48132182,"uuid":"220342117","full_name":"shimmeringbee/zstack","owner":"shimmeringbee","description":"Implementation of a ZNP and support code designed to interface with Texas Instruments Z-Stack, written in Go.","archived":false,"fork":false,"pushed_at":"2024-07-14T07:08:20.000Z","size":265,"stargazers_count":27,"open_issues_count":1,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-13T21:44:34.261Z","etag":null,"topics":["cc2530","cc2531","cc253x","go","z-stack","zigbee-network-processor","znp"],"latest_commit_sha":null,"homepage":"https://shimmeringbee.io/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shimmeringbee.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-07T22:43:26.000Z","updated_at":"2024-08-21T05:26:22.000Z","dependencies_parsed_at":"2024-07-14T08:37:49.438Z","dependency_job_id":null,"html_url":"https://github.com/shimmeringbee/zstack","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/shimmeringbee%2Fzstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shimmeringbee%2Fzstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shimmeringbee%2Fzstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shimmeringbee%2Fzstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shimmeringbee","download_url":"https://codeload.github.com/shimmeringbee/zstack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252753716,"owners_count":21798998,"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":["cc2530","cc2531","cc253x","go","z-stack","zigbee-network-processor","znp"],"created_at":"2024-08-02T23:00:59.809Z","updated_at":"2025-05-06T19:32:22.922Z","avatar_url":"https://github.com/shimmeringbee.png","language":"Go","readme":"# Shimmering Bee: Z-Stack\n\n[![license](https://img.shields.io/github/license/shimmeringbee/zstack.svg)](https://github.com/shimmeringbee/zstack/blob/master/LICENSE)\n[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg)](https://github.com/RichardLitt/standard-readme)\n[![Actions Status](https://github.com/shimmeringbee/zstack/workflows/test/badge.svg)](https://github.com/shimmeringbee/zstack/actions)\n\n\u003e Implementation of a ZNP and support code designed to interface with Texas Instruments Z-Stack, written in Go.\n\n## Table of Contents\n\n- [Background](#background)\n- [Install](#install)\n- [Usage](#usage)\n- [Maintainers](#maintainers)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Background\n\nZ-Stack is a Zigbee Stack made available by Texas Instruments for use on their CC 2.4Ghz SOC processors. This \nlibrary implements a Zigbee Network Processor that is capable of controlling a Z-Stack implementation, specifically it\nsupports the CC series of Zigbee sniffers flashed with the \n[zigbee2mqtt](https://www.zigbee2mqtt.io/getting_started/flashing_the_cc2531.html) Z-Stack coordinator firmware.\n\nMore information about Z-Stack is available from [Texas Instruments](https://www.ti.com/tool/Z-STACK) directly or from\n[Z-Stack Developer's Guide](https://usermanual.wiki/Pdf/ZStack20Developers20Guide.1049398016/view).\n\n[Another implementation](https://github.com/dyrkin/znp-go/) of a Z-Stack compatible ZNP exists for Golang, it did [hold no license for a period](https://github.com/dyrkin/zigbee-steward/issues/1)\nand the author could not be contacted. This has been rectified, so it may be of interest you. This is a complete\nreimplementation of the library, however it is likely there will be strong coincidences due to Golang standards.\n\n## Supported Devices\n\nThe following chips and sticks are known to work, though it's likely others in the series will too:\n\n* CC253X\n  * Cheap Zigbee Sniffers from AliExpress - CC2531\n* CC26X2R1\n  * [Electrolama zig-a-sig-ah!](https://electrolama.com/projects/zig-a-zig-ah/) - CC2652R\n   \nHuge thanks to @Koenkk for his work in providing Z-Stack firmware for these chips. You can [grab the firmware from GitHub](https://github.com/Koenkk/Z-Stack-firmware/).\n\n## Install\n\nAdd an import and most IDEs will `go get` automatically, if it doesn't `go build` will fetch.\n\n```go\nimport \"github.com/shimmeringbee/zstack\"\n```\n\n## Usage\n\n**This libraries API is unstable and should not yet be relied upon.**\n\n### Open Serial Connection and Start ZStack\n\n```go\n/* Obtain a ReadWriter UART interface to CC253X */\nserialPort :=\n\n/* Construct node table, cache of network nodes. */\nt := zstack.NewNodeTable()\n\n/* Create a new ZStack struct. */\nz := zstack.New(serialPort, t)\n\n/* Generate random Zigbee network, on default channel (15) */\nnetCfg, _ := zigbee.GenerateNetworkConfiguration()\n\n/* Obtain context for timeout of initialisation. */\nctx, cancel := context.WithTimeout(context.Background(), 2 * time.Minute)\ndefer cancel()\n\n/* Initialise ZStack and CC253X */)\nerr = z.Initialise(ctx, nc)\n```\n\n### Handle Events\n\n**It is critical that this is handled until you wish to stop the Z-Stack instance.**\n\n```go\nfor {\n    ctx := context.Background()\n    event, err := z.ReadEvent(ctx)\n\n    if err != nil {\n        return\n    }\n\n    switch e := event.(type) {\n    case zigbee.NodeJoinEvent:\n        log.Printf(\"join: %v\\n\", e.Node)\n        go exploreDevice(z, e.Node)\n    case zigbee.NodeLeaveEvent:\n        log.Printf(\"leave: %v\\n\", e.Node)\n    case zigbee.NodeUpdateEvent:\n        log.Printf(\"update: %v\\n\", e.Node)\n    case zigbee.NodeIncomingMessageEvent:\n        log.Printf(\"message: %v\\n\", e)\n    }\n}\n```\n\n### Permit Joins\n\n```go\nerr := z.PermitJoin(ctx, true)\n```\n\n### Deny Joins\n\n```go\nerr := z.DenyJoin(ctx)\n```\n\n### Query Device For Details\n\n```go\nfunc exploreDevice(z *zstack.ZStack, node zigbee.Node) {\n\tlog.Printf(\"node %v: querying\", node.IEEEAddress)\n\n\tctx, cancel := context.WithTimeout(context.Background(), 1 * time.Minute)\n\tdefer cancel()\n\n\tdescriptor, err := z.QueryNodeDescription(ctx, node.IEEEAddress)\n\n\tif err != nil {\n\t\tlog.Printf(\"failed to get node descriptor: %v\", err)\n\t\treturn\n\t}\n\n\tlog.Printf(\"node %v: descriptor: %+v\", node.IEEEAddress, descriptor)\n\n\tendpoints, err := z.QueryNodeEndpoints(ctx, node.IEEEAddress)\n\n\tif err != nil {\n\t\tlog.Printf(\"failed to get node endpoints: %v\", err)\n\t\treturn\n\t}\n\n\tlog.Printf(\"node %v: endpoints: %+v\", node.IEEEAddress, endpoints)\n\n\tfor _, endpoint := range endpoints {\n\t\tendpointDes, err := z.QueryNodeEndpointDescription(ctx, node.IEEEAddress, endpoint)\n\n\t\tif err != nil {\n\t\t\tlog.Printf(\"failed to get node endpoint description: %v / %d\", err, endpoint)\n\t\t} else {\n\t\t\tlog.Printf(\"node %v: endpoint: %d desc: %+v\", node.IEEEAddress, endpoint, endpointDes)\n\t\t}\n\t}\n}\n```\n\n### Node Table Cache\n\n`zstack` requires a `NodeTable` structure to cache a devices IEEE address to its Zibgee network address. A design \ndecision for `zstack` was that all operations would reference the IEEE address. This cache must be persisted between \nprogram runs as the coordinator hardware does not retain this information between restarts.\n\n```go\n// Create new table\nnodeTable := NewNodeTable()\n\n// Dump current content\nnodes := nodeTable.Nodes()\n\n// Load previous content - this should be done before starting ZStack.\nnodeTable.Load(nodes)\n```\n\n### ZCL\n\nTo handle ZCL messages you must handle `zigbee.NodeIncomingMessageEvent` messages and process the ZCL payload with the ZCL library, responses can be sent with `z.SendNodeMessage`.\n\n## Maintainers\n\n[@pwood](https://github.com/pwood)\n\n## Contributing\n\nFeel free to dive in! [Open an issue](https://github.com/shimmeringbee/zstack/issues/new) or submit PRs.\n\nAll Shimmering Bee projects follow the [Contributor Covenant](https://shimmeringbee.io/docs/code_of_conduct/) Code of Conduct.\n\n## License\n\n   Copyright 2019-2020 Shimmering Bee Contributors\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.","funding_links":[],"categories":["Repositories"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshimmeringbee%2Fzstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshimmeringbee%2Fzstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshimmeringbee%2Fzstack/lists"}