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

Guidelines

Some quick guidelines to keep the codebase maintainable:

• No external production dependencies
• Mark TODO / XXX / @deprecated in code as needed for quick access
• Performance in mind (with the goal to eventually bring the appropriate layers to a lower language as needed)
  • No expensive calls (stringify, etc.)
  • Bail as early as possible (no unnecessary parsing, holding waiters, etc.)
  • Ability to no-op expensive "optional" features
  • And the usuals...
• Keep MAC/ZigBee property naming mostly in line with Wireshark for easier debugging
• Keep in line with the ZigBee 3.0 specification, but allow optimization due to the host-driven nature and removal of unnecessary features that won't impact compatibility
• Focus on "Centralized Trust Center" implementation (at least at first)

Current status

[~] Partial feature, [?] Uncertain feature

• [x] Encoding/decoding of Spinel & HDLC protocols
• [x] Encoding/decoding of MAC frames
• [x] Encoding/decoding of ZigBee NWK frames
  • [ ] Lacking reference sniffs for multicast (group)
• [x] Encoding/decoding of ZigBee NWK GP frames
• [x] Encoding/decoding of ZigBee NWK APS frames
• [x] Network forming
• [x] Network state saving (de facto backups)
• [x] Network state reset
• [x] Joining/Rejoining
  • [x] APS TC link key update mechanism (global)
  • [x] Direct child router
  • [x] Direct child end device
  • [x] Nested device
• [x] Indirect transmission mechanism
• [x] Source routing
• [ ] Route repairing
• [x] Coordinator LQI/Routing tables (for network map data on coordinator side)
• [x] LQI reporting
  • [ ] Refining
• [ ] Install codes
• [?] APS APP link keys
• [ ] InterPAN / Touchlink
• [ ] R23 (need reference sniffs...)
• [~] Security
• [ ] Metrics/Statistics
• [ ] 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:

• 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: 460800
  # as appropriate for your coordinator/firmware, unused for TCP-based coordinator
  rtscts: 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.dev' and 'compose.dev.yaml'

Prerequisites

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

Running util commands

Create 'zoh.save' (details above):

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

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

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

CLI:

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

Stopping & removing the container

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