house.zigbee.automations

Time based, MQTT triggered, room, global, dimmer, presence and greeting automations. 81 options.

General

house.zigbee.automations

Modular automations for zigduck. Each submodule groups a family of related event sources:

mqtt_triggered -> fires when an MQTT topic publishes a matching payload time_based -> fires on a cron expression or structured schedule presence_based -> fires after motion has been absent for a configured duration greeting -> fires when the entry door opens after the house has been empty dimmer_actions -> per-room overrides for dimmer button events room_actions -> hooks for internal zigduck room events global_actions -> hooks for internal zigduck global events

All submodules share the action DSL defined by Types.automationActionType, so any action can be used in any submodule. Conditions are not shared: mqtt_triggered and time_based accept dark_time | someone_home | room_occupied, while presence_based accepts dark_time | room_occupied | lights_on.

Type: submodule

Default: { }

Declared in: options/zigbee/automations.nix

house.zigbee.automations.global_actions

Global automation hooks fired by internal zigduck events that are not scoped to a room. Key is the event name (e.g. leak_detected, smoke_detected, all_lights_on, security_armed); value is an ordered action list. String entries are shorthand for { type = "shell"; command = <string>; }.

Type: attribute set of list of (string or (submodule))

Default: { }

Example:

{
  leak_detected = [
    {
      message = " ";
      topic = "zigduck/effects/flash";
      type = "mqtt";
    }
    {
      scene = "max";
      type = "scene";
    }
    {
      command = "zigduck-cli --notify '💧 WATER LEAK DETECTED!'";
      type = "shell";
    }
  ];
  smoke_detected = [
    {
      message = " ";
      topic = "zigduck/effects/flash";
      type = "mqtt";
    }
    {
      scene = "max";
      type = "scene";
    }
    {
      command = "zigduck-cli --notify '🔥 FIRE/SMOKE DETECTED!' --tag critical";
      type = "shell";
    }
  ];
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.room_actions

Room-scoped automation hooks fired by internal zigduck events. Outer key is the room name (must match a room under house.rooms); inner key is the event name emitted by the room event bus (e.g. motion_detected, motion_not_detected, door_opened, door_closed, lights_turned_on); the value is an ordered action list. String entries are shorthand for { type = "shell"; command = <string>; }.

Type: attribute set of attribute set of list of (string or (submodule))

Default: { }

Example:

{
  hallway = {
    door_closed = [ ];
    door_opened = [
      {
        command = "zigduck-cli --notify '🚪 DOOR OPEN!'";
        type = "shell";
      }
      {
        command = "curl http://192.168.1.15/api/settings/speaker/play/ding";
        type = "shell";
      }
    ];
  };
  kitchen = {
    motion_detected = [
      {
        scene = "kitchenInstant";
        type = "scene";
      }
    ];
    motion_not_detected = [
      {
        scene = "kitchenFadeOff";
        type = "scene";
      }
    ];
  };
}

Declared in: options/zigbee/automations.nix

dimmer_actions

house.zigbee.automations.dimmer_actions

Per-room overrides for dimmer-switch behaviour. The attribute name must match a room declared under house.rooms. The reserved key _default defines the baseline applied to every room that does not override a given event; each concrete room inherits _default and may override any subset of the eight button events.

Type: attribute set of (submodule)

Default: { }

Example:

{
  _default = {
    down_hold_release = {
      description = "Default: no default actions";
      enable = true;
    };
    down_press_release = {
      description = "Default: dim down room lights";
      enable = true;
    };
    off_hold_release = {
      description = "Default: turn off all lights";
      enable = true;
    };
    off_press_release = {
      description = "Default: turn off room lights";
      enable = true;
    };
    on_hold_release = {
      description = "Default: turn on all lights at maximum brightness";
      enable = true;
    };
    on_press_release = {
      description = "Default: turn on room lights";
      enable = true;
    };
    up_hold_release = {
      description = "Default: no default actions";
      enable = true;
    };
    up_press_release = {
      description = "Default: dim up room lights";
      enable = true;
    };
  };
  kitchen = {
    off_press_release = {
      description = "Turn off kitchen lights only";
      enable = true;
    };
    on_press_release = {
      description = "Turn on kitchen lights and fan";
      enable = true;
      extra_actions = [
        {
          message = "{\"state\":\"ON\"}";
          topic = "zigbee2mqtt/Fläkt/set";
          type = "mqtt";
        }
      ];
    };
  };
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.down_hold_release

Override for the down-button hold-and-release event. null uses the built-in default (no action).

Type: null or (submodule)

Default: null

Example:

{
  description = "Nothing by default";
  enable = true;
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.down_hold_release.description

Human-readable description of what this handler does. Shown in generated documentation.

Type: string

Example: "Turn off the kitchen fan on hold-release"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.down_hold_release.enable

Whether to enable Enable this dimmer action.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.down_hold_release.extra_actions

Actions appended after the dimmer’s default behaviour. Use this to add side effects (e.g. switch a fan on) without replacing the built-in dimming logic.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    message = "{\"state\":\"ON\"}";
    topic = "zigduck/Fläkt/set";
    type = "mqtt";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.down_hold_release.override_actions

If non-empty, replaces the default dimmer behaviour entirely with these actions. Use this to repurpose a button (e.g. hold “off” to run a scene instead of merely dimming).

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "dark";
    type = "scene";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.down_press_release

Override for the down-button press-and-release event. null uses the built-in default (dim room lights down).

Type: null or (submodule)

Default: null

Example:

{
  description = "Dim room lights down";
  enable = true;
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.down_press_release.description

Human-readable description of what this handler does. Shown in generated documentation.

Type: string

Example: "Turn off the kitchen fan on hold-release"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.down_press_release.enable

Whether to enable Enable this dimmer action.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.down_press_release.extra_actions

Actions appended after the dimmer’s default behaviour. Use this to add side effects (e.g. switch a fan on) without replacing the built-in dimming logic.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    message = "{\"state\":\"ON\"}";
    topic = "zigduck/Fläkt/set";
    type = "mqtt";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.down_press_release.override_actions

If non-empty, replaces the default dimmer behaviour entirely with these actions. Use this to repurpose a button (e.g. hold “off” to run a scene instead of merely dimming).

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "dark";
    type = "scene";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.off_hold_release

Override for the off-button hold-and-release event. null uses the built-in default (turn off all lights).

Type: null or (submodule)

Default: null

Example:

{
  description = "Turn off all lights and the kitchen fan";
  enable = true;
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.off_hold_release.description

Human-readable description of what this handler does. Shown in generated documentation.

Type: string

Example: "Turn off the kitchen fan on hold-release"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.off_hold_release.enable

Whether to enable Enable this dimmer action.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.off_hold_release.extra_actions

Actions appended after the dimmer’s default behaviour. Use this to add side effects (e.g. switch a fan on) without replacing the built-in dimming logic.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    message = "{\"state\":\"ON\"}";
    topic = "zigduck/Fläkt/set";
    type = "mqtt";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.off_hold_release.override_actions

If non-empty, replaces the default dimmer behaviour entirely with these actions. Use this to repurpose a button (e.g. hold “off” to run a scene instead of merely dimming).

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "dark";
    type = "scene";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.off_press_release

Override for the off-button press-and-release event. null uses the built-in default (turn off room lights).

Type: null or (submodule)

Default: null

Example:

{
  description = "Turn off room lights only";
  enable = true;
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.off_press_release.description

Human-readable description of what this handler does. Shown in generated documentation.

Type: string

Example: "Turn off the kitchen fan on hold-release"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.off_press_release.enable

Whether to enable Enable this dimmer action.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.off_press_release.extra_actions

Actions appended after the dimmer’s default behaviour. Use this to add side effects (e.g. switch a fan on) without replacing the built-in dimming logic.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    message = "{\"state\":\"ON\"}";
    topic = "zigduck/Fläkt/set";
    type = "mqtt";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.off_press_release.override_actions

If non-empty, replaces the default dimmer behaviour entirely with these actions. Use this to repurpose a button (e.g. hold “off” to run a scene instead of merely dimming).

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "dark";
    type = "scene";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.on_hold_release

Override for the on-button hold-and-release event. null uses the built-in default (turn on all lights).

Type: null or (submodule)

Default: null

Example:

{
  description = "Turn on every light in the house";
  enable = true;
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.on_hold_release.description

Human-readable description of what this handler does. Shown in generated documentation.

Type: string

Example: "Turn off the kitchen fan on hold-release"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.on_hold_release.enable

Whether to enable Enable this dimmer action.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.on_hold_release.extra_actions

Actions appended after the dimmer’s default behaviour. Use this to add side effects (e.g. switch a fan on) without replacing the built-in dimming logic.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    message = "{\"state\":\"ON\"}";
    topic = "zigduck/Fläkt/set";
    type = "mqtt";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.on_hold_release.override_actions

If non-empty, replaces the default dimmer behaviour entirely with these actions. Use this to repurpose a button (e.g. hold “off” to run a scene instead of merely dimming).

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "dark";
    type = "scene";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.on_press_release

Override for the on-button press-and-release event in this room. null uses the built-in default (turn on room lights). See the top-level _default example for the baseline behaviour of every event.

Type: null or (submodule)

Default: null

Example:

{
  description = "Turn on kitchen lights and fan";
  enable = true;
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.on_press_release.description

Human-readable description of what this handler does. Shown in generated documentation.

Type: string

Example: "Turn off the kitchen fan on hold-release"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.on_press_release.enable

Whether to enable Enable this dimmer action.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.on_press_release.extra_actions

Actions appended after the dimmer’s default behaviour. Use this to add side effects (e.g. switch a fan on) without replacing the built-in dimming logic.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    message = "{\"state\":\"ON\"}";
    topic = "zigduck/Fläkt/set";
    type = "mqtt";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.on_press_release.override_actions

If non-empty, replaces the default dimmer behaviour entirely with these actions. Use this to repurpose a button (e.g. hold “off” to run a scene instead of merely dimming).

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "dark";
    type = "scene";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.up_hold_release

Override for the up-button hold-and-release event. null uses the built-in default (no action).

Type: null or (submodule)

Default: null

Example:

{
  description = "Nothing by default";
  enable = true;
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.up_hold_release.description

Human-readable description of what this handler does. Shown in generated documentation.

Type: string

Example: "Turn off the kitchen fan on hold-release"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.up_hold_release.enable

Whether to enable Enable this dimmer action.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.up_hold_release.extra_actions

Actions appended after the dimmer’s default behaviour. Use this to add side effects (e.g. switch a fan on) without replacing the built-in dimming logic.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    message = "{\"state\":\"ON\"}";
    topic = "zigduck/Fläkt/set";
    type = "mqtt";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.up_hold_release.override_actions

If non-empty, replaces the default dimmer behaviour entirely with these actions. Use this to repurpose a button (e.g. hold “off” to run a scene instead of merely dimming).

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "dark";
    type = "scene";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.up_press_release

Override for the up-button press-and-release event. null uses the built-in default (dim room lights up).

Type: null or (submodule)

Default: null

Example:

{
  description = "Dim room lights up";
  enable = true;
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.up_press_release.description

Human-readable description of what this handler does. Shown in generated documentation.

Type: string

Example: "Turn off the kitchen fan on hold-release"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.up_press_release.enable

Whether to enable Enable this dimmer action.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.up_press_release.extra_actions

Actions appended after the dimmer’s default behaviour. Use this to add side effects (e.g. switch a fan on) without replacing the built-in dimming logic.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    message = "{\"state\":\"ON\"}";
    topic = "zigduck/Fläkt/set";
    type = "mqtt";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.dimmer_actions.<name>.up_press_release.override_actions

If non-empty, replaces the default dimmer behaviour entirely with these actions. Use this to repurpose a button (e.g. hold “off” to run a scene instead of merely dimming).

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "dark";
    type = "scene";
  }
]

Declared in: options/zigbee/automations.nix

greeting

house.zigbee.automations.greeting

The welcome-home automation. Fires actions when the configured door opens after the house has been empty for at least awayDuration seconds.

Type: submodule

Default: { }

Example:

{
  actions = [
    {
      command = "yo say 'Welcome home!'";
      type = "shell";
    }
  ];
  awayDuration = 7200;
  delay = 10;
  door = "Door Sensor Hall";
  enable = true;
  message = "contact";
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.greeting.actions

Ordered actions executed on arrival. The default is a shell echo; most users override this with a TTS command or a notification. String entries are shorthand for { type = "shell"; command = <string>; }.

Type: list of (string or (submodule))

Default:

[
  "echo 'Welcome home!'"
]

Example:

[
  {
    command = "yo say 'Welcome home!'";
    type = "shell";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.greeting.awayDuration

Minimum seconds the house must have been empty before a door opening counts as “arriving home”. Prevents the greeting from firing when you just stepped out to take out the trash.

Type: signed integer

Default: 7200

Example: 7200

Declared in: options/zigbee/automations.nix

house.zigbee.automations.greeting.delay

Seconds to wait after the door opens before running actions. Useful when the greeting is TTS that should play after the door has closed again.

Type: signed integer

Default: 10

Example: 10

Declared in: options/zigbee/automations.nix

house.zigbee.automations.greeting.door

Friendly name of the door sensor to watch. Required when enable = true; the automation is a no-op when this is null. Must match a friendly_name under house.zigbee.devices. Case-sensitive.

Type: null or string

Default: null

Example: "Door Sensor Hall"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.greeting.enable

Whether to enable the greeting automation.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.greeting.message

Field on the door sensor’s state payload that flips to false when the door opens. For most Zigbee contact sensors this is "contact"; override only when using a custom sensor with a different field name.

Type: string

Default: "contact"

Example: "contact"

Declared in: options/zigbee/automations.nix

mqtt_triggered

house.zigbee.automations.mqtt_triggered

Automations driven by incoming MQTT messages. Each attribute name is the automation’s identifier (free-form, shown in logs). Runs actions when topic receives a matching message and every optional conditions entry passes.

Type: attribute set of (submodule)

Default: { }

Example:

{
  button_single_press = {
    actions = [
      {
        message = "{\"state\":\"TOGGLE\"}";
        topic = "zigbee2mqtt/living_room_lights/set";
        type = "mqtt";
      }
    ];
    description = "Toggle living room lights on single button press";
    enable = true;
    message = "single";
    topic = "zigbee2mqtt/living_room_button/action";
  };
  motion_alert = {
    actions = [
      "echo 'Motion detected outside!' | wall"
      {
        command = "/nix/store/hf9wcn7jhcynf4ihndzbscbknx97in30-libnotify-0.8.8/bin/notify-send 'Security' 'Motion detected outside'";
        type = "shell";
      }
    ];
    description = "Send notification on outdoor motion";
    enable = true;
    message = "true";
    topic = "zigbee2mqtt/outdoor_motion/occupancy";
  };
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.mqtt_triggered.<name>.actions

Ordered actions executed when topic (and message, if set) match and all conditions pass. String entries are shorthand for { type = "shell"; command = <string>; }.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "kitchenInstant";
    type = "scene";
  }
  {
    duration = 5;
    type = "wait";
  }
  "echo 'automation completed'"
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.mqtt_triggered.<name>.conditions

Conditions that must all pass before actions run. Empty list means the automation fires unconditionally on a matching message.

Type: list of (submodule)

Default: [ ]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.mqtt_triggered.<name>.conditions.*.room

Room the condition applies to. Required when type = "room_occupied"; ignored otherwise.

Type: null or string

Default: null

Example: "kitchen"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.mqtt_triggered.<name>.conditions.*.type

Condition to evaluate before running actions:

dark_time -> current time is within the dark window configured under house.zigbee.motion.trigger.lights someone_home -> at least one presence tracker reports home room_occupied-> the room named in room currently reports occupancy

Type: one of “dark_time”, “someone_home”, “room_occupied”

Example: "dark_time"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.mqtt_triggered.<name>.conditions.*.value

Expected boolean for the condition. The condition passes when the computed state equals value. null means “any non-empty value”.

Type: null or boolean

Default: null

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.mqtt_triggered.<name>.description

Human-readable summary shown in logs and generated documentation. Does not affect behaviour.

Type: string

Example: "Toggle living room lights on single button press"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.mqtt_triggered.<name>.enable

Whether to enable Enable this MQTT-triggered automation.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.mqtt_triggered.<name>.message

If set, actions fire only when the published payload equals this string exactly. null (the default) fires on every message published to topic, regardless of payload.

Type: null or string

Default: null

Example: "single"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.mqtt_triggered.<name>.topic

MQTT topic the automation subscribes to. Must be fully qualified with the broker’s baseTopic prefix (default: zigbee2mqtt/).

Type: string

Example: "zigbee2mqtt/living_room_button/action"

Declared in: options/zigbee/automations.nix

presence_based

house.zigbee.automations.presence_based

Automations driven by motion absence. Each entry watches one or more motion sensors and fires actions after no_motion_duration seconds of stillness, then optionally fires motion_restored_actions when motion returns.

Type: attribute set of (submodule)

Default: { }

Example:

{
  kitchen_idle = {
    actions = [
      {
        scene = "kitchenFadeOff";
        type = "scene";
      }
      {
        message = "{\"state\":\"OFF\"}";
        topic = "zigduck/Fläkt/set";
        type = "mqtt";
      }
    ];
    conditions = [
      {
        room = "kitchen";
        type = "lights_on";
        value = true;
      }
    ];
    description = "Turn off kitchen lights and fan after 10 minutes with no motion";
    enable = true;
    motion_restored_actions = [
      {
        scene = "kitchenInstant";
        type = "scene";
      }
    ];
    motion_sensors = [
      "Motion Sensor Kök"
    ];
    no_motion_duration = 600;
  };
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.presence_based.<name>.actions

Ordered actions executed after no_motion_duration seconds without motion, provided every condition passes. String entries are shorthand for { type = "shell"; command = <string>; }.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "kitchenFadeOff";
    type = "scene";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.presence_based.<name>.conditions

Conditions that must all pass before actions run. motion_restored_actions is not gated by these.

Type: list of (submodule)

Default: [ ]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.presence_based.<name>.conditions.*.room

Room the condition applies to. Required when type is room-scoped (room_occupied); ignored otherwise.

Type: null or string

Default: null

Example: "kitchen"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.presence_based.<name>.conditions.*.type

Condition to evaluate before actions run:

dark_time -> currently inside the dark window room_occupied-> the room currently reports occupancy (useful to suppress auto-off if someone just returned) lights_on -> at least one light in scope is currently on (skips the work when everything is already off)

Type: one of “dark_time”, “room_occupied”, “lights_on”

Example: "lights_on"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.presence_based.<name>.conditions.*.value

Expected boolean for the condition. Passes when the computed state equals value.

Type: null or boolean

Default: null

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.presence_based.<name>.description

Human-readable summary shown in logs and generated documentation. Does not affect behaviour.

Type: string

Example: "Turn off kitchen lights after 10 minutes idle"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.presence_based.<name>.enable

Whether to enable this presence-based automation.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.presence_based.<name>.motion_restored_actions

Ordered actions executed when motion is detected again after actions has fired. Use this to restore lighting without waiting for the normal motion handler to catch up. Not gated by conditions.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "kitchenInstant";
    type = "scene";
  }
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.presence_based.<name>.motion_sensors

Friendly names of the motion sensors to watch. The automation considers the room idle once every sensor in this list has reported no motion for no_motion_duration seconds.

Type: list of string

Default: [ ]

Example:

[
  "Motion Sensor Kök"
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.presence_based.<name>.no_motion_duration

Seconds of continuous no-motion before actions fire. A single motion event resets the countdown.

Type: signed integer

Default: 300

Example: 600

Declared in: options/zigbee/automations.nix

time_based

house.zigbee.automations.time_based

Automations driven by a schedule. schedule accepts either a cron expression or a structured window; see its description for both forms.

Type: attribute set of (submodule)

Default: { }

Example:

{
  bedtime = {
    actions = [
      {
        scene = "dark";
        type = "scene";
      }
    ];
    description = "Prepare the house for bed every night";
    enable = true;
    schedule = "0 22 * * *";
  };
  morning_wakeup = {
    actions = [
      {
        scene = "morning";
        type = "scene";
      }
      "echo 'Good morning!'"
    ];
    conditions = [
      {
        type = "someone_home";
        value = true;
      }
    ];
    description = "Gentle morning lights on weekdays";
    enable = true;
    schedule = {
      days = [
        "mon"
        "tue"
        "wed"
        "thu"
        "fri"
      ];
      end = "07:00";
      start = "06:30";
    };
  };
}

Declared in: options/zigbee/automations.nix

house.zigbee.automations.time_based.<name>.actions

Ordered actions executed when the schedule and every condition match. String entries are shorthand for { type = "shell"; command = <string>; }.

Type: list of (string or (submodule))

Default: [ ]

Example:

[
  {
    scene = "morning";
    type = "scene";
  }
  "echo 'Good morning!'"
]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.time_based.<name>.conditions

Conditions that must all pass at fire time. Empty list means the automation fires unconditionally.

Type: list of (submodule)

Default: [ ]

Declared in: options/zigbee/automations.nix

house.zigbee.automations.time_based.<name>.conditions.*.room

Room the condition applies to. Required when type = "room_occupied"; ignored otherwise.

Type: null or string

Default: null

Example: "bedroom"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.time_based.<name>.conditions.*.type

Same condition vocabulary as mqtt_triggered:

dark_time -> currently inside the dark window someone_home -> at least one presence tracker home room_occupied-> the room named in room reports occupancy

Type: one of “dark_time”, “someone_home”, “room_occupied”

Example: "someone_home"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.time_based.<name>.conditions.*.value

Expected boolean for the condition. Passes when the computed state equals value.

Type: null or boolean

Default: null

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.time_based.<name>.description

Human-readable summary shown in logs and generated documentation. Does not affect behaviour.

Type: string

Example: "Gentle morning lights on weekdays"

Declared in: options/zigbee/automations.nix

house.zigbee.automations.time_based.<name>.enable

Whether to enable this time-based automation.

Type: boolean

Default: false

Example: true

Declared in: options/zigbee/automations.nix

house.zigbee.automations.time_based.<name>.schedule

When the automation fires. Either:

string-> a standard 5-field cron expression (e.g. "0 22 * * *" = every day at 22:00)

attrset-> structured { start; end; days; } for the common “within this window” case

Type: string or (submodule)

Example:

{
  days = [
    "mon"
    "tue"
    "wed"
    "thu"
    "fri"
  ];
  end = "07:00";
  start = "06:30";
}

Declared in: options/zigbee/automations.nix