Zigbee on Host

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.

Development

CONTRIBUTING

Current status

Percentages generated by copilot based on overall compliance.

Protocol	Status	Pending
Spinel & HDLC	100%	—
IEEE 802.15.4 MAC	100%	—
Zigbee NWK	90%	Route discovery table, TLV parsing
Zigbee APS	85%	TLV parsing, APS security enablement, fragment sizing/ack heuristics, counter persistence
Zigbee Green Power	80%	Commissioning TLVs, security checking, counter persistence, security review (MIC/auth tag flows & key usage)

Feature	Status	Pending
Network forming & state	100%	—
Joining & rejoining workflow	90%	Key update detection, apsTrustCenterAddress validation
Indirect transmission mechanism	90%	Queue depth/back-pressure heuristics
Source routing	75%	Discovery table enforcement, single-entry normalization, pruning policy
Route repairing	55%	Automated path rebuild, repair acknowledgements telemetry
Coordinator LQI/routing	85%	Age/diversity metrics, reporting hooks
LQI reporting & mapping	70%	Adaptive calibration, exposure via metrics interface
Install code	100%	—
APS application link keys	80%	Usage (currently DISALLOWED), per-pair derivation, attribute persistence, rotation tooling
InterPAN / Touchlink	0%	Entire feature set
R23 compliance (commissioning & TLVs)	40%	Commissioning TLVs, Zigbee Direct, optional behaviors
Trust Center key rotation	15%	Scheduler, counter telemetry, alerting
Security hardening	65%	Rejoin anomaly detection, Trust Center policy gating, alert fan-out
Metrics & statistics	0%	Collection/export of all pending telemetry items

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] Some CC13xx/CC26xx boards require skipping the bootloader on startup. If ZoH does not want to start (timeout on first contact), set "tiSerialSkipBootloader": true in custom stack config.
• [Texas Instruments] Does not currently implement PHY_CCA_THRESHOLD (cannot read or write value)

Testing

Current Status

• CI: ~95% 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:

• Silicon Labs: https://github.com/Nerivec/silabs-firmware-builder/releases
• Texas Instruments: https://github.com/Koenkk/OpenThread-TexasInstruments-firmware/releases
• Nordic Semiconductor: https://github.com/Nerivec/zigbee-on-host/discussions/18

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:

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

Custom stack config

Starting with zigbee-herdsman 6.4.0, it is possible to provide a custom stack configuration via JSON (similar to ember's).

interface StackConfigJSON {
    /** for TI hw only, required for some CC13xx/CC26xx with auto-entering of bootloader on plug in */
    tiSerialSkipBootloader: boolean;
    /** EUI64 used for the adapter -- 0x${hex} format */
    eui64: string;
    /** @see https://nerivec.github.io/zigbee-on-host/types/spinel_spinel.StreamRawConfig.html */
    ccaBackoffAttempts: number;
    /** @see https://nerivec.github.io/zigbee-on-host/types/spinel_spinel.StreamRawConfig.html */
    ccaRetries: number;
    /** @see https://nerivec.github.io/zigbee-on-host/types/spinel_spinel.StreamRawConfig.html */
    enableCSMACA: boolean;
}
Copy

Defaults are:

{
    "tiSerialSkipBootloader": false,
    "eui64": "0x4d325a6e6f486f5a",
    "ccaBackoffAttempts": 1,
    "ccaRetries": 4,
    "enableCSMACA": true
}
Copy

CLI & Utils

Clone the repository.

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

Install dev dependencies and build:

npm ci
npm run build
Copy

Utils

Create a 'zoh.save' from the content of a Zigbee2MQTT data folder

npm run dev:z2z ./path/to/data/
Copy

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/
Copy

CLI

Get a list of supported commands with:

npm run dev:cli help
Copy

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
Copy

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
Copy

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
Copy

CLI:

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

Stopping & removing the container

docker compose -f docker-dev/compose.yaml down
Copy