feat(zigbee): add Zigbee Herdsman plugin for direct Zigbee device integration

[akadlec]

Summary

This PR introduces a comprehensive Zigbee Herdsman plugin that enables direct Zigbee device integration via the zigbee-herdsman library. The plugin provides self-contained Zigbee network management with device discovery, adoption, and real-time monitoring capabilities.

Key Changes

Backend Implementation

• Core Services

  • ZigbeeHerdsmanAdapterService: Wraps zigbee-herdsman Controller with typed events and lifecycle management for serial communication with Zigbee coordinators
  • ZigbeeHerdsmanService: Main plugin service implementing IManagedPluginService interface for plugin lifecycle and state management
  • ZhDeviceAdoptionService: Handles device adoption workflow with automatic channel and property mapping
  • ZhMappingPreviewService: Generates device mapping previews before adoption with customizable expose overrides
  • ZhDeviceConnectivityService: Monitors device connectivity with configurable timeouts for mains and battery-powered devices

• Configuration & Models

  • ZigbeeHerdsmanConfigModel: Complete configuration model with serial port, network, discovery, and database settings
  • ZigbeeHerdsmanDiscoveredDeviceModel: Response model for discovered devices with interview status and availability tracking
  • Comprehensive response models for mapping previews, coordinator info, and device adoption

• Controllers & DTOs

  • ZigbeeHerdsmanDiscoveredDevicesController: REST API endpoints for device discovery, permit join, mapping preview, and device adoption
  • Request/response DTOs with full validation and Swagger documentation

• Constants & Mappings

  • Device type mappings (Coordinator, Router, EndDevice)
  • Channel category mappings from Zigbee exposes (light, switch, thermostat, sensors, etc.)
  • Property bindings for common Zigbee properties (state, brightness, temperature, humidity, etc.)
  • Interview status tracking (not_started, in_progress, completed, failed)

• Database Entities

  • ZigbeeHerdsmanDeviceEntity: Extends base DeviceEntity with IEEE address and device type
  • ZigbeeHerdsmanChannelEntity: Channel entity for Zigbee devices
  • ZigbeeHerdsmanChannelPropertyEntity: Channel property entity for device properties

• Platform Integration

  • ZigbeeHerdsmanDevicePlatform: Implements IDevicePlatform interface for device command execution and property updates

• Exception Handling

  • Custom exceptions for connection failures, validation errors, coordinator offline scenarios, and command execution failures

Admin UI Implementation

• Configuration Form (zigbee-herdsman-config-form.vue)

  • Serial port configuration (path, baud rate, adapter type)
  • Network settings (channel, PAN ID, extended PAN ID, network key)
  • Discovery settings (permit join timeout)
  • Database configuration

• Device Management Forms

  • Device add form with IEEE address, name, and category selection
  • Device edit form for updating device properties
  • Mapping preview component for visualizing device structure before adoption

• Store & Schemas

  • Zod schemas for configuration, devices, channels, and channel properties
  • Store type definitions for type-safe state management
  • Locale support with English translations

Plugin Integration

• Module registration in both backend (app.module.ts) and admin (app.main.ts)
• Full OpenAPI documentation with extra models
• Plugin lifecycle management with proper initialization and cleanup

Notable Implementation Details

• Exposes Format Compatibility: Uses the same exposes format as zigbee2mqtt since both leverage zigbee-herdsman-converters
• Device Interview Tracking: Monitors device interview status to ensure devices are properly configured before use
• Flexible Mapping: Supports customizable property mappings with expose overrides during device adoption
• Connectivity Monitoring: Implements separate timeout strategies for mains-powered and battery-powered devices
• Serial Communication: Supports multiple adapter types (auto, zstack, ember, deconz, zigate) with configurable b

https://claude.ai/code/session_014bjB9Cn1WKASNLBeCuSbom

---

Note

High Risk
Introduces a large new devices plugin with new REST endpoints, device-command execution logic, and a database migration adding columns to core device/channel-property tables. Also updates backend dependencies and touches existing Shelly reconnect behavior, increasing integration and runtime risk.

Overview
Adds a new Zigbee Herdsman devices plugin end-to-end (admin + backend), enabling direct coordinator-based Zigbee device discovery, mapping preview, adoption, permit-join control, and command execution via zigbee-herdsman/zigbee-herdsman-converters.

On the backend, registers the plugin module, adds new controller/DTOs/models/services/entities (including a device platform for sending toZigbee commands with retries), and introduces a TypeORM migration that extends devices_module_devices and devices_module_channels_properties with Zigbee-specific columns.

On the admin side, wires the plugin into app.main.ts, adds config/device add/edit forms with validation and i18n strings, and adds Zod schemas to match the new plugin config and device type. Also adjusts apps/backend/package.json (version bump + new Zigbee/serial dependencies) and refines Shelly NG forceReconnect() to terminate the socket and reset reconnect backoff.

^{Reviewed by Cursor Bugbot for commit 39c89a7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 39c89a7. Configure here.}

[cursor]

Removed delegate members still referenced elsewhere

High Severity

The disconnectedAt field and the pollStatus method were removed from ShellyDeviceDelegate, but delegates-manager.service.ts still references both (checkHealth reads delegate.disconnectedAt to decide whether to force reconnect, and pollAllDevices calls delegate.pollStatus(timeoutMs)). This breaks the type check and, at runtime, makes stale-disconnect detection and the periodic status poll non-functional, effectively disabling energy-counter refresh and stuck-socket recovery for Shelly NG devices.

Additional Locations (1)

• apps/backend/src/plugins/devices-shelly-ng/delegates/shelly-device.delegate.ts#L211-L235

 

^{Reviewed by Cursor Bugbot for commit 39c89a7. Configure here.}