zigbee-herdsman: the low-level Zigbee library under Zigbee2MQTT

A library, not a gateway you can install and run

zigbee-herdsman is described as an open source Zigbee gateway solution with a Node.js JavaScript runtime back end, and the repository description calls it a Node.js Zigbee library. The distinction matters for anyone deciding what to install. This is the component that speaks the Zigbee protocol to a coordinator and the devices, and it is a dependency of gateway software rather than a finished product. The README points at the two projects that use it, and those descriptions are the clearest statement of purpose available. Zigbee2MQTT is a Zigbee to MQTT gateway that bridges events and lets you control Zigbee devices over MQTT, so you can use your devices without the vendors' proprietary and closed source bridges, and it keeps track of the state of the system and the capabilities of connected devices. It uses zigbee-herdsman and zigbee-herdsman-converters as modules for the low-level core Zigbee communication. ioBroker uses zigbee-herdsman for its Zigbee integration, as part of a home automation platform focused on building automation, smart metering, ambient assisted living, process automation, visualisation and data logging.

A fork of zigbee-shepherd, refactored for maintainability

The project was originally forked from zigbee-shepherd with the goal of refactoring it to improve maintainability, and that sentence explains a lot about the codebase. The reader coming from zigbee-shepherd should expect the same protocol work arranged differently, while the reader coming fresh should expect something that grew out of a working library rather than a clean-sheet design. The repository layout is consistent with a mature TypeScript library: src for the code, test for the suite, examples, scripts, a pnpm lockfile and a pnpm workspace file, a release-please configuration with its manifest, a CHANGELOG.md, a biome.json for formatting and linting, and a tsconfig.json. The release tooling deserves a note, because release-please means the changelog and the version bumps are generated from commit messages rather than typed by hand, and the README points to CHANGELOG.md for complete release notes including breaking changes. The API reference is automatically generated and published at koenkk.github.io/zigbee-herdsman.

The dependency list shows where the hardware work happens

The runtime dependencies are short and they describe the architecture. The serial port stack is the core of it, with @serialport/bindings-cpp, @serialport/parser-delimiter and @serialport/stream, which is how the library talks to a USB coordinator adapter. The slip package handles SLIP framing, the serial protocol used to carry Zigbee frames over the serial line. zigbee-on-host is the piece that runs the Zigbee stack on the host, and the bonjour-service dependency is for discovering devices on the local network by name. The rest is utility: @date-fns/tz for time zone handling, debounce for taming noisy input, and fast-deep-equal for comparison. The keywords published for the package list zigbee alongside zstack, emberznet, deconz and zigate, which are the firmware families and coordinator vendors the library is expected to work with. The devDependencies show the tooling: Vitest with coverage, Biome, TypeScript and rimraf, with a mock serial port binding so the suite can run without hardware.

How the package is published, and what a consumer sees

The packaging metadata is worth reading, because it tells you how the library is consumed. The package name is zigbee-herdsman, the licence is MIT and the description is an open source Zigbee gateway solution with node.js. The distribution is CommonJS, with main pointing at ./dist/index.js, types at ./dist/index.d.ts, and a module field also pointing at ./dist/index.js, so the same build serves the require and import paths. The project pins its package manager in the manifest, with packageManager set to [email protected], and the repository ships a pnpm lockfile and a pnpm workspace file, which is consistent with a monorepo layout that also holds zigbee-herdsman-converters. The author is Koen Kanters, with Hedy Wang, Simen Li and Jack Wu listed as contributors, and the issues link points to koenkk/zigbee-herdsman.

Joining a device: the example, and the AGENTS files

The examples directory contains a single file, join-and-log.js, and it is the closest thing the repository offers to a first use. There is no install command in the README, so the practical starting point is a checkout, a pnpm install, and running that example against a coordinator and a device. The repository also carries AGENTS.md and an AI_POLICY.md alongside the code, which tells you that the project expects contributions from coding agents as well as people, and that there is a stated policy about how those contributions are handled. The CHANGELOG.md and the generated API reference between them are the documentation you will actually use, and the 11.x line has been moving quickly, with v11.0.2 on 2026-10-07, v11.0.3 on 2026-10-09 and v11.1.0 on 2026-10-13, and the last push on 2026-10-19.

Where this library stops and the gateway begins

The limitation to be clear about is scope. zigbee-herdsman does not give you an MQTT broker, a dashboard, a rule engine or a device database in any usable form, and it does not solve the problem of which devices to buy. Its job is the part closest to the radio, the coordinator and the devices, and it expects the caller to supply credentials, pairing and the application model. The alternative approach is a vendor's own bridge, which the README argues against for a specific reason, that it lets you use your devices without the vendors' proprietary and closed source bridges or gateways, and the reason Zigbee2MQTT tracks system state and device capabilities is that the tracking has to live somewhere. A second difference is that the converters live in a separate project, zigbee-herdsman-converters, so a device that depends on manufacturer-specific clusters is a dependency of the gateway layer as much as of this library. If what you want is lights in a dashboard, a gateway project is the right starting point and this library is one layer below it.

Editorial conclusion

zigbee-herdsman fits a developer building a Zigbee gateway or a custom bridge that needs raw device control rather than a vendor app, and who is prepared to sit close to the protocol. It does not fit a user who wants their lights in Home Assistant, since the intended entry point is a gateway project such as Zigbee2MQTT. Before adopting it, read the CHANGELOG for breaking changes at the 11.x line, check that your adapter firmware is one the library supports, and expect to handle the serial port and pairing yourself rather than getting a finished application.

Frequently asked questions

Official sources

1. Issues
2. Koenkk/zigbee-herdsman on GitHub
3. License: MIT
4. README
5. Releases