Generic Actor Version 2

The generic2 actor can be used for controlling different types of entities like numbers or media players, even those having multiple adjustable attributes such as roller shutters with tilt and position.

It works by defining a set of values and, for each of these values, what services have to be called in order to reach the state represented by that value.

Instead of a single value such as "on" or "off", you may also generate a tuple of multiple values like (50, 75) or ("on", 10) in your schedule rules, where each slot in that tuple corresponds to a different attribute of the entity.

If you want to see how this actor type can be used, have a look at the Switch.

Configuration

This is a full actor configuration with comments on each available setting. The default values are provided as well. If you don’t need a particular setting, omit it or leave it commented out.

# Here you configure the attributes of the entity to be controlled by the schedule.
attributes:
  # The attribute to be controlled, this could be e.g. "state" or "brightness".
  # A value of null creates a write-only attribute. This has to be used when you want
  # to control a property whose current value is not reflected in any of the entity's
  # attributes. Don't do this if not really necessary, since doing so means that
  # Schedy won't be able to verify that the value has been transmitted correctly. If
  # you must use a write-only attribute, you might also want to set send_retries to a
  # low value in order to avoid excessive network load.
- attribute: first
- attribute: second
- ...

# Here you configure the values you want to be able to return from your schedule.
values:
  # Each value is a list of the values for the individual attributes configured above.
  # Schedy compares the entity's current attributes against the values defined here
  # in order to find the value currently active.
  # The special attribute value "*" is a wildcard and will, when used, match any
  # value of that particular attribute.
  # Additionally, you don't have to include all attributes in every single value,
  # only the first N attributes which values are provided for are compared against
  # the entity's state for the value to match.
- value: ["on", "*"]
  # The services that have to be called in order to make the actor report this value.
  calls:
    # Which service to call
  - service: ...
    # Optionally, provide a mapping with data to be passed with the service call.
    # You can use "{attr1}" as a placeholder for the value set for the first attribute,
    # "{attr2}" for the value of the second attribute and so on to pass the correct
    # attribute values to the service call as needed in order to bring the entity
    # to the state represented by the value you returned from your schedule.
    # The placeholder "{entity_id}" can be used to insert the actor's entity id.
    # For instance, if the value
    #   ["on", 75]
    # was returned by a schedule, the following sample would render to:
    #   {"param1": "something", "param2": 75}
    data:
      param1: "something"
      param2: "{attr2}"
    # Set to false if you don't want the entity_id field to be included in service
    # data automatically.
    #include_entity_id: true

# More values#
- ...

# Set this to true if you want Schedy to treat string attributes of an entity the
# same, no matter if they're reported in lower or upper case. This is handy for some
# MQTT devices, for instance, which sometimes report a state of "ON", while others say
# "on".
#ignore_case: false

Supported Values

Every value that has been configured in the values section of the actor configuration may be returned from a schedule.

Examples:

- v: "on"
- x: "-40 if is_on(...) else Next()"

As soon as you configure multiple slots (attributes to be controlled), a list or tuple with a value for each attribute is expected. The order is the same in which the slots were specified in the configuration.

Examples:

- v: ['on', 20]
- x: "(-40, 'something') if is_on(...) else Next()"

Note

When specifying the values on and off, enclose them in quotes as shown above to inform the YAML parser you don’t mean the booleans True and False instead.