Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

zigbee-on-host

Nerivec19.4kGPL-3.0-or-later0.1.13TypeScript support: included

ZigBee stack designed to run on a host and communicate with a radio co-processor (RCP)

zigbee, host, stack, rcp

readme

ZigBee on Host

Version CI CodeQL

Open Source ZigBee stack designed to run on a host and communicate with a radio co-processor (RCP).

Current 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.

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.

[!IMPORTANT] Work in progress! Expect breaking changes without backwards compatibility for a while!

Development

CONTRIBUTING

Current status

[~] Partial feature, [?] Uncertain feature

  • <input checked="" disabled="" type="checkbox"> Encoding/decoding of Spinel & HDLC protocols
  • <input checked="" disabled="" type="checkbox"> Encoding/decoding of MAC frames
  • <input checked="" disabled="" type="checkbox"> Encoding/decoding of ZigBee NWK frames
    • <input disabled="" type="checkbox"> Lacking reference sniffs for multicast (group)
  • <input checked="" disabled="" type="checkbox"> Encoding/decoding of ZigBee NWK GP frames
  • <input checked="" disabled="" type="checkbox"> Encoding/decoding of ZigBee NWK APS frames
  • <input checked="" disabled="" type="checkbox"> Network forming
  • <input checked="" disabled="" type="checkbox"> Network state saving (de facto backups)
  • <input checked="" disabled="" type="checkbox"> Network state reset
  • <input checked="" disabled="" type="checkbox"> Joining/Rejoining
    • <input checked="" disabled="" type="checkbox"> APS TC link key update mechanism (global)
    • <input checked="" disabled="" type="checkbox"> Direct child router
    • <input checked="" disabled="" type="checkbox"> Direct child end device
    • <input checked="" disabled="" type="checkbox"> Nested device
  • <input checked="" disabled="" type="checkbox"> Indirect transmission mechanism
  • <input checked="" disabled="" type="checkbox"> Source routing
  • <input disabled="" type="checkbox"> Route repairing
  • <input checked="" disabled="" type="checkbox"> Coordinator LQI/Routing tables (for network map data on coordinator side)
  • <input checked="" disabled="" type="checkbox"> LQI reporting
    • <input disabled="" type="checkbox"> Refining
  • <input disabled="" type="checkbox"> Install codes
  • [?] APS APP link keys
  • <input disabled="" type="checkbox"> InterPAN / Touchlink
  • <input disabled="" type="checkbox"> R23 (need reference sniffs...)
  • [~] Security
  • <input disabled="" type="checkbox"> Metrics/Statistics
  • <input disabled="" type="checkbox"> Big cleanup of unused / never will use!

And likely more, and of course a bunch of TODOs in the code!

You can also contribute by submitting sniffs/captures. More information here.

OpenThread RCP firmware notes

  • [Texas Instruments] Does not currently implement PHY_CCA_THRESHOLD (cannot read or write value)

Testing

Current Status

  • CI: ~70% coverage
  • Stress-testing: pending
  • Firmware stability:
    • Silicon Labs: ongoing
    • Texas Instruments: ongoing
    • Nordic Semiconductor: pending
  • Usage in test networks: ongoing
  • Usage in live networks: pending

Firmware

Use the appropriate OpenThread RCP firmware for your adapter:

Zigbee2MQTT

Zigbee2MQTT 2.1.3-dev (after PR #26742) and later versions should allow the use of the zoh adapter. Make sure you followed the above steps to get the proper firmware, then configure your configuration.yaml, including:

[!TIP] It is currently recommended you use Zigbee2MQTT latest-dev (edge) to get the latest fixes when testing this implementation!

serial:
  port: /dev/serial/by-id/my-device-id-here
  adapter: zoh
  # unused for TCP-based coordinator
  baudrate: 460800
  # as appropriate for your coordinator/firmware, unused for TCP-based coordinator
  rtscts: true

[!TIP] 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. 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.

[!TIP] 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).

CLI & Utils

Clone the repository.

git clone https://github.com/Nerivec/zigbee-on-host
cd zigbee-on-host

Install dev dependencies and build:

npm ci
npm run build

[!IMPORTANT] Running npm run build:prod omits the src/dev directory (for production). If you do, you will not be able to use dev:* commands.

[!TIP] If having issues with building, try removing the *.tsbuildinfo incremental compilation files (or run npm run clean first).

Utils

Create a 'zoh.save' from the content of a Zigbee2MQTT data folder
npm run dev:z2z ./path/to/data/

[!TIP] 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).

Print and save the content of the 'zoh.save' in the given directory in human-readable format (as JSON, in same directory)
npm run dev:z2r ./path/to/data/
CLI

Get a list of supported commands with:

npm run dev:cli help

[!TIP] 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 & wireshark. The effective config is printed at the start of every command (help included).

Using Docker
Prerequisites
git clone https://github.com/Nerivec/zigbee-on-host
cd zigbee-on-host
docker compose -f docker-dev/compose.yaml up -d --pull never
docker compose -f docker-dev/compose.yaml exec zigbee-on-host npm ci
docker compose -f docker-dev/compose.yaml exec zigbee-on-host npm run build
Running util commands

Create 'zoh.save' (details above):

docker compose -f docker-dev/compose.yaml exec zigbee-on-host npm run dev:z2z ./path/to/data

Print readable 'zoh.save' content (details above):

docker compose -f docker-dev/compose.yaml exec zigbee-on-host npm run dev:z2r ./path/to/data

CLI:

docker compose -f docker-dev/compose.yaml exec zigbee-on-host npm run dev:cli help

[!TIP] 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 & wireshark from the compose file. The effective config is printed at the start of every command (help included).

Stopping & removing the container
docker compose -f docker-dev/compose.yaml down