Generic Actor

Warning

This actor type has been superseeded by the Generic Actor Version 2. Use that instead.

The generic 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 service has to be called in order to reach the state represented by that value. Together with a wildcard for undefined values, this is a quite powerful mechanism.

Instead of a single value such as "on" or "off", you may also generate a tuple with 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.

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.

# List the entity attributes to be controlled by this actor.
attributes:

- # The attribute of the entity to be watched for state changes.
  # Use "state" for the entity state or any other attribute from the
  # attributes dictionary.
  # When you set this to null, you define a write-only attribute which's
  # current value isn't reflected in the entity's state and thus can't be
  # determined by Schedy. The configured service is called when setting a
  # value, but the value can never be considered committed and re-sending
  # is done according to the send_retries and send_retry_interval settings.
  #attribute: null

  # Here, the possible values of that attribute are configured.
  # Values can be floats, integers, strings or null.
  values:

    #some_value:

      # The service that needs to be called in order to make the attribute
      # show this value.
      #service: <required>

      # The data to be passed to the service.
      #service_data: {}

      # Whether to include the entity id as "entity_id" in the service data.
      #include_entity_id: true

      # The parameter as which the actual value should be passed in the
      # service data.
      # null means not include the value in the service data.
      #value_parameter: null

    #other_value:
      # ...

    # The keyword "_other_" stands for a so-called wildcard value that
    # matches any value not explicitly defined here. You may want to use
    # the wildcard value to catch arbitrary numbers, for example.
    # If you define all possible values explicitly and don't need a wildcard,
    # simply leave it out.
    #_other_:
      # ...

- # Second attribute...


# By default, services for changing the different attributes are called
# in the order you defined the attributes. Set this flag to true to have
# the order in which services are called reversed.
#call_reversed: false


# For some types of actors that need multiple attributes to be
# controlled, there are sometimes attributes that aren't important in
# a particular state. For instance, a light that's turned off doesn't
# care about the brightness or color set.
# For these kind of actors, you can configure short values: values which
# only need to have the first N attributes set.
# You of course need to configure the attributes in an order that makes
# sense, with mandatory ones first and state-specific ones later.
short_values:
# When the first attribute is set to "off", don't consider further
# attributes.
- ["off"]
# When the first attribute is set to "on" and the second's value is
# something catched by the wildcard value, ignore further attributes.
- ["on", "_other_"]

Supported Values

The generic actor can be used in two ways. When just a single attribute should be controlled, every value for which a service has been configured in the values section of the actor configuration may be returned by a schedule. If you have the wildcard value _other_ configured, any value is accepted.

Examples:

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

As soon as you add multiple attributes to control, a list or tuple with a value for each attribute is expected. The order is the same in which the attributes 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.