/zigbee2mqtt-extensions

Create simple automations directly in zigbee2mqtt

Primary LanguageTypeScriptMIT LicenseMIT

Zigbee2MQTT Extensions

Enjoy my work? Help me out for a couple of 🍻 or a ☕!

coffee

What are extensions?

Read this article

automations-extension.js

Allows you to set up simple automations directly in z2m

Example (add this into your z2m configuration.yaml):

automations:
  automation_by_action:
    trigger:
      platform: action
      entity: Test Switch
      action: single
    condition:
      platform: state
      entity: Test Switch 2
      state: ON
    action:
      entity: Test Plug
      service: toggle

  automation_by_state:
    trigger:
      platform: state
      entity: Test Plug
      state: ON
    action:
      entity: Test Plug 2
      service: turn_on

  automation_by_numeric_state:
    trigger:
      platform: numeric_state
      entity: Test Plug
      attribute: temperatire
      above: 17
      below: 26
      for: 3
    action:
      entity: Test Plug
      service: turn_on

More complex example:

automations:
  automation_by_action:
    trigger:
      platform: action
      entity:
      - Test Switch
      - Test Button
      action:
      - single
      - double
      - hold
    condition:
      - platform: state
        entity: Test Switch 2
        state: ON
      - platform: numeric_state
        entity: My Sensor
        attribute: temperature
        above: 25
        below: 35
    action:
    - entity: Test Plug
      service: toggle
    - entity: Test Plug 2
      service: toggle

  automation_by_state:
    trigger:
      platform: state
      entity:
      - Test Plug
      - Test Plug 2
      state:
      - ON
      - OFF
    action:
    - entity: Test Light 1
      service: turn_on
    - entity: Test Light 2
      service: turn_off

Split configuration

You can move automations to a separate file. Create file named automations.yaml and write all your automations there:

# configuration.yaml

automations: automations.yaml
# automations.yaml

automation_by_action:
  trigger:
    platform: action
    entity: Test Switch
    action: single
  condition:
    platform: state
    entity: Test Switch 2
    state: ON
  action:
    entity: Test Plug
    service: toggle

State Trigger

Fires when state of given entities changes.

Item Type Description
platform string state
entity string or string[] Name of entity (friendly name)
state string, string[], number, number[], boolean, boolean[] Depends on attribute. ON/OFF for state, true/false for occupancy
attribute string Optional (default state). temperatire, humidity, pressure and others device-specific
for number Number of seconds

Examples:

trigger:
  platform: state
  entity:
    - My Switch
    - My Light
  state: ON
  for: 10
trigger:
  platform: state
  entity: Motion Sensor
  attribute: occupancy
  state: true

Numeric State Trigger

Fires when numeric attribute of given entities changes. Parameters above or below (or both) should be set.

Item Type Description
platform string numeric_state
entity string or string[] Name of entity (friendly name)
attribute string temperatire, humidity, pressure and others device-specific
above number Triggers when value crosses a given threshold
below number Triggers when value crosses a given threshold
for number Number of seconds

Example:

trigger:
  platform: numeric_state
  entity: My Sensor
  attribute: temperature
  above: 25
  below: 35
  for: 180

Conditions

Conditions are an optional part of an automation rule and can be used to prevent an action from happening when triggered. When a condition does not return true, the automation will stop executing. Conditions look very similar to triggers but are very different. A trigger will look at events happening in the system while a condition only looks at how the system looks right now. A trigger can observe that a switch is being turned on. A condition can only see if a switch is currently on or off.

Automation can have multiple conditions

State Condition

Tests if an entity is a specified state.

Item Type Description
platform string state
entity string Name of entity (friendly name)
state string, number, boolean Depends on attribute. ON/OFF for state, true/false for occupancy
attribute string Optional (default state). temperatire, humidity, pressure and others device-specific

Examples:

condition:
  platform: state
  entity: My Switch
  state: ON
condition:
  platform: state
  entity: Motion Sensor
  attribute: occupancy
  state: false

Numeric State Condition

This type of condition attempts to parse the attribute of an entity as a number, and triggers if the value matches the thresholds.

If both below and above are specified, both tests have to pass.

Item Type Description
platform string numeric_state
entity string Name of entity (friendly name)
attribute string temperatire, humidity, pressure and others device-specific
above number Triggers when value crosses a given threshold
below number Triggers when value crosses a given threshold

Example:

condition:
  platform: numeric_state
  entity: My Sensor
  attribute: temperature
  above: 25
  below: 35

Time Condition

The time condition can test if it is after a specified time, before a specified time or if it is a certain day of the week.

Item Type Description
platform string time
after string Optional (time in hh:mm:ss format)
before string Optional (time in hh:mm:ss format)
weekday string[] Optional (valid values: mon, tue, wed, thu, fri, sat, sun)

Note that if only before key is used, the condition will be true from midnight until the specified time. If only after key is used, the condition will be true from the specified time until midnight.

Time condition windows can span across the midnight threshold if both after and before keys are used. In the example below, the condition window is from 3pm to 2am.

Example:

condition:
  platform: time
  after: '15:00:00'
  before: '02:00:00'
  weekday:
    - mon
    - wed
    - fri

Actions

The action of an automation rule is what is being executed when a rule fires.

Automation can have multiple actions

Item Type Description
entity string Name of entity (friendly name)
service string turn_on, turn_off, toggle or custom
data {string: string} Only for service: custom, see below

Example:

action:
  - entity: Test Plug
    service: toggle
  - entity: Test Switch
    service: turn_on

Custom action

You can call any service. Data will be transferred directly to Z2M. For example change brightness or turn on a relay with a custom name.

Example:

action:
  - entity: Plug With Two Relays
    service: custom
    data:
      state_l2: ON
  - entity: Light Strip
    service: custom
    data:
      state: ON
      brightness: 127
      transition: 2