house.zigbee

Coordinator, Mosquitto, Zigbee devices, scenes, dimmers, motion and the Hue Sync Box. 63 options.

General

`house.zigbee.dataDir`

Zigbee2mqtt data directory

Type: absolute path

Default: "/var/lib/zigbee"

Example: "/var/lib/zigbee2mqtt"

Declared in: options/zigbee/zigbee.nix

`house.zigbee.enable`

Whether to enable zigbee2mqtt service.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/zigbee.nix

`house.zigbee.networkKeyFile`

Path to a file containing the Zigbee network key used by Zigbee2MQTT (network_key).

The network key identifies and secures the Zigbee network. Keep this key stable: changing or losing it will require Zigbee devices to be paired with the network again.

The file should contain the key in the following format:

- 86
- 208
...

Type: absolute path

Example: "/run/secrets/zigbee_key"

Declared in: options/zigbee/zigbee.nix

`house.zigbee.scenes`

Scenes for Zigbee devices

Type: attribute set of attribute set of (attribute set)

Default: { }

Declared in: options/zigbee/scenes.nix

`house.zigbee.settings`

Please note that this flake already handles the configuration of Zigbee2MQTT internally. These would be overrides. Your configuration.yaml as a Nix attribute set. Check the documentation for possible options.

Type: YAML 1.1 value

Default: { }

Example:

{
  homeassistant.enabled = config.services.home-assistant.enable;
  permit_join = true;
  serial = {
    port = "/dev/ttyACM1";
  };
}

Declared in: options/zigbee/zigbee.nix

coordinator

`house.zigbee.coordinator`

Serial port device mapping by USB IDs

Type: null or (submodule)

Default: { }

Declared in: options/zigbee/coordinator.nix

`house.zigbee.coordinator.adapter`

Zigbee2MQTT adapter type used to communicate with the coordinator.

For Zigbee2MQTT 2.x and newer, this should normally be set to the adapter type expected by your coordinator. Common values include “zstack” for Texas Instruments coordinators.

If you are unsure, leave the default value unchanged.

Type: string

Default: "zstack"

Declared in: options/zigbee/coordinator.nix

`house.zigbee.coordinator.productId`

USB product ID of the Zigbee coordinator, in hexadecimal.

You can find this with lsusb. For example, if it reports ID 10c3:ea61, the product ID is ea61.

Together with vendorId, this identifies the coordinator USB device.

Type: string

Declared in: options/zigbee/coordinator.nix

`house.zigbee.coordinator.symlink`

Name of the stable symlink to create under /dev.

For example, setting this to “zigbee” creates /dev/zigbee, which can then be used as the serial device for Zigbee2MQTT.

Using a symlink avoids depending on unstable device names such as /dev/ttyUSB0, which can change when USB devices are plugged in or removed.

Type: string

Declared in: options/zigbee/coordinator.nix

`house.zigbee.coordinator.vendorId`

USB vendor ID of the Zigbee coordinator, in hexadecimal.

You can find this with lsusb. For example, if it reports ID 10c3:ea61, the vendor ID is 10c3.

This is used together with productId to identify the correct USB device, regardless of which /dev/ttyUSB* or /dev/ttyACM* device name Linux assigns to it.

Type: string

Declared in: options/zigbee/coordinator.nix

devices

`house.zigbee.devices`

Zigbee device definitions keyed by device ID.

Type: attribute set of (submodule)

Default: { }

Declared in: options/zigbee/devices.nix

`house.zigbee.devices.<name>.batteryType`

Optional type of battery the device uses.

Type: null or string

Default: null

Declared in: options/zigbee/devices.nix

`house.zigbee.devices.<name>.endpoint`

The Zigbee endpoint to control this device.

Type: signed integer

Example: 11

Declared in: options/zigbee/devices.nix

`house.zigbee.devices.<name>.friendly_name`

A human-readable device name.

Type: string

Example: "Kitchen Dimmer"

Declared in: options/zigbee/devices.nix

`house.zigbee.devices.<name>.hue_id`

The light_id for the device (Hue integration).

Type: null or signed integer

Default: null

Declared in: options/zigbee/devices.nix

`house.zigbee.devices.<name>.icon`

Material Design icon name representing this device.

Type: string

Default: "mdi:duck"

Declared in: options/zigbee/devices.nix

`house.zigbee.devices.<name>.room`

The room this device belongs to.

Example: "kitchen"

Declared in: options/zigbee/devices.nix

`house.zigbee.devices.<name>.supports_color`

Whether the light supports color.

Type: boolean

Default: false

Declared in: options/zigbee/devices.nix

`house.zigbee.devices.<name>.supports_temperature`

Whether the light supports temperature.

Type: boolean

Default: false

Declared in: options/zigbee/devices.nix

`house.zigbee.devices.<name>.type`

The type of device.

Type: one of “light”, “hue_light”, “dimmer”, “sensor”, “motion”, “outlet”, “remote”, “pusher”, “blind”, “custom”

Example: "light"

Declared in: options/zigbee/devices.nix

dimmer

`house.zigbee.dimmer`

Configuration for dimmer switches. Default configuration is for the Philips Hue Dimmer Switch. You can check the message for your specific dimmer at zigbee2MQTT documentation.

Type: submodule

Default:

{
  actions = {
    downHold = "down_hold_release";
    downPress = "down_press_release";
    offHold = "off_hold_release";
    offPress = "off_press_release";
    onHold = "on_hold_release";
    onPress = "on_press_release";
    upHold = "up_hold_release";
    upPress = "up_press_release";
  };
  message = "action";
}

Declared in: options/zigbee/dimmer.nix

`house.zigbee.dimmer.actions.downHold`

Action for holding DOWN button

Type: string

Default: "down_hold_release"

Declared in: options/zigbee/dimmer.nix

`house.zigbee.dimmer.actions.downPress`

Action for single press of DOWN button

Type: string

Default: "down_press_release"

Declared in: options/zigbee/dimmer.nix

`house.zigbee.dimmer.actions.offHold`

Action for holding OFF button

Type: string

Default: "off_hold_release"

Declared in: options/zigbee/dimmer.nix

`house.zigbee.dimmer.actions.offPress`

Action for single press of OFF button

Type: string

Default: "off_press_release"

Declared in: options/zigbee/dimmer.nix

`house.zigbee.dimmer.actions.onHold`

Action for holding ON button

Type: string

Default: "on_hold_release"

Declared in: options/zigbee/dimmer.nix

`house.zigbee.dimmer.actions.onPress`

Action for single press of ON button

Type: string

Default: "on_press_release"

Example: "on_press_release"

Declared in: options/zigbee/dimmer.nix

`house.zigbee.dimmer.actions.upHold`

Action for holding UP button

Type: string

Default: "up_hold_release"

Declared in: options/zigbee/dimmer.nix

`house.zigbee.dimmer.actions.upPress`

Action for single press of UP button

Type: string

Default: "up_press_release"

Declared in: options/zigbee/dimmer.nix

`house.zigbee.dimmer.doubleClickTimeout`

Timeout for double‑click detection in milliseconds. Double clicking will result in scene cycle on the lights in the dimmmers defined room.

Type: null or signed integer

Default: 300

Example: 500

Declared in: options/zigbee/dimmer.nix

`house.zigbee.dimmer.message`

MQTT field name containing dimmer action

Type: string

Default: "action"

Example: "action"

Declared in: options/zigbee/dimmer.nix

hueSyncBox

`house.zigbee.hueSyncBox`

Philips Hue Bridge & Sync Box configuration for TV to lights syncing

Type: null or (submodule)

Default: null

Declared in: options/zigbee/hue-sync-box.nix

`house.zigbee.hueSyncBox.bridge.ip`

IP address of the Philips Hue Bridge

Type: string

Declared in: options/zigbee/hue-sync-box.nix

`house.zigbee.hueSyncBox.bridge.passwordFile`

Path to a file containing the Hue Bridge API key (username). To get a key, press the physical button on your Hue Bridge, then run: curl -X POST http://<bridge-ip>/api -d ‘{“devicetype”:“house#nixos”}’ The response will contain a username field – save that string in this file.

Type: absolute path

Declared in: options/zigbee/hue-sync-box.nix

`house.zigbee.hueSyncBox.enable`

Whether to enable Enable Philips Hue Bridge & Sync Box integration.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/hue-sync-box.nix

`house.zigbee.hueSyncBox.syncBox.ip`

IP address of the Philips Hue Sync Box

Type: string

Declared in: options/zigbee/hue-sync-box.nix

`house.zigbee.hueSyncBox.syncBox.passwordFile`

Path to a file containing the Hue Sync Box API token. To get a token, run the following command: curl -k -sS -X POST “https://<SYNC_BOX_IP>/api/v1/registrations” -H “Content-Type: application/json” -d ‘{“appName”: “zigduck”, “instanceName”: “zigduck”}’ Then press and hold the physical button on the Sync Box until the LED turns green, then send the command again. The resposne will contain the API token.

Type: absolute path

Declared in: options/zigbee/hue-sync-box.nix

`house.zigbee.hueSyncBox.syncBox.tv`

What TV should syncBox syncronize the lights to. Available TVs: shield

Type: string

Default: ""

Example: "shield"

Declared in: options/zigbee/hue-sync-box.nix

mosquitto

`house.zigbee.mosquitto`

Type: null or (submodule)

Declared in: options/zigbee/mosquitto.nix

`house.zigbee.mosquitto.baseTopic`

MQTT base topic used by Zigbee2mqtt and the zigduck runtime.

Type: string

Default: "zigbee2mqtt"

Example: "zigduck"

Declared in: options/zigbee/mosquitto.nix

`house.zigbee.mosquitto.host`

IP address of the host running Mosquitto

Type: null or string

Default: null

Example: "192.168.1.211"

Declared in: options/zigbee/mosquitto.nix

`house.zigbee.mosquitto.passwordFile`

Path to file containing MQTT password

Type: null or absolute path

Default: null

Example: "/run/secrets/mosquitto"

Declared in: options/zigbee/mosquitto.nix

`house.zigbee.mosquitto.ssl.caCertFile`

Path to CA certificate file

Type: null or absolute path

Default: null

Declared in: options/zigbee/mosquitto.nix

`house.zigbee.mosquitto.ssl.clientCertFile`

Path to client certificate file

Type: null or absolute path

Default: null

Declared in: options/zigbee/mosquitto.nix

`house.zigbee.mosquitto.ssl.clientKeyFile`

Path to client private key file

Type: null or absolute path

Default: null

Declared in: options/zigbee/mosquitto.nix

`house.zigbee.mosquitto.ssl.enable`

Whether to enable Enable SSL/TLS for MQTT connection.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/mosquitto.nix

`house.zigbee.mosquitto.username`

MQTT username for authentication

Type: null or string

Default: null

Example: "mqtt-user"

Declared in: options/zigbee/mosquitto.nix

`house.zigbee.mosquitto.whitelist`

Optional list of additional JSON fields to include in states.json

Type: list of string

Default: [ ]

Example:

[
  "special_key"
  "device_state"
]

Declared in: options/zigbee/mosquitto.nix

motion

`house.zigbee.motion`

Type: submodule

Default: { }

Declared in: options/zigbee/motion.nix

`house.zigbee.motion.enable`

Whether to enable Enable Zigbee motion handling.

Type: boolean

Default: true

Example: true

Declared in: options/zigbee/motion.nix

`house.zigbee.motion.trigger`

Type: submodule

Default: { }

Declared in: options/zigbee/motion.nix

`house.zigbee.motion.trigger.lights`

Motion-triggered lighting behavior

Type: submodule

Default: { }

Declared in: options/zigbee/motion.nix

`house.zigbee.motion.trigger.lights.after`

Lights activate only after this hour (24h)

Type: signed integer

Default: 16

Declared in: options/zigbee/motion.nix

`house.zigbee.motion.trigger.lights.before`

Lights activate only before this hour (24h)

Type: signed integer

Default: 9

Declared in: options/zigbee/motion.nix

`house.zigbee.motion.trigger.lights.duration`

Seconds to keep lights on after motion

Type: signed integer

Default: 900

Declared in: options/zigbee/motion.nix

`house.zigbee.motion.trigger.lights.transition`

Wether to fade out the lights for the configured duration, instead of waiting for it.

Type: boolean

Default: false

Declared in: options/zigbee/motion.nix

`house.zigbee.motion.when.dark.enable`

Whether to enable Enable Zigbee motion handling.

Type: boolean

Default: true

Example: true

Declared in: options/zigbee/motion.nix

no.motion

`house.zigbee.no.motion`

Type: submodule

Default: { }

Declared in: options/zigbee/no-motion.nix

`house.zigbee.no.motion.trigger.all`

Type: submodule

Default: { }

Declared in: options/zigbee/no-motion.nix

`house.zigbee.no.motion.trigger.all.lights.off`

No motion-triggered lighting behavior

Type: submodule

Default: { }

Declared in: options/zigbee/no-motion.nix

`house.zigbee.no.motion.trigger.all.lights.off.after`

Time in minutes without motion that trigger all lights off.

Type: signed integer

Default: 180

Declared in: options/zigbee/no-motion.nix

`house.zigbee.no.motion.trigger.all.lights.off.enable`

Whether to enable Enable Zigbee motion handling.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/no-motion.nix

`house.zigbee.no.motion.trigger.all.lights.off.exclude`

List of devices (strings) to exclude, leaving them in current state.

Type: list of string

Default: [ ]

Declared in: options/zigbee/no-motion.nix