/docs/MyDocs

Terminology

===========

Devices                 - Some physical device, basically integration (driver) instance.

Entities                - Device components (e.g. specific buttons on light switch, temperature and humidity sensors in weather station, etc.). Entities expose services which can be called, e.g. turn_on/turn_off for smartbulbs.

                        Entity defined by its id which has the following format: "<domain>.<device_uid>_<entity>", e.g. switch.0x5c0272fffee160ef_right, sensor.0x00158d0006c667fa_pressure, light.yeelight_color_0x7caaf86

                        Also other components are exposed as entities, e.g. 'automation', 'zone', etc.

Domain                  - Type of entity, e.g. switch, light, sensor, etc.

Object/Area             - Kitchen, hall, bedroom, ...

States                  - Each entity has a state (and a number of attributes). State machine associated with entities. Changes to state machine is not propogated to devices (and will be overwritten if device is polled)

 

Variables

=========

 Context-specific

 ----------------

    trigger                                                     - Trigger causing current code to run

      {.id, .idx, .platform, .entity_id}                        - Most of triggers

      { .event, .event_type, .event.data}                       - Event/device/entity triggers

      {.topic, .payload, .payload_json, .qos)                   - MQTT triggers

      {.from_state, .to_state, .for, .bellow, .above }          - Numeric/State

    this                                                        - State object of entity

      {.state, .domain, .entity_id, .object_id}                 .object_id=<object> (e.g. kitchen), .entity_id=<domain>.<object_id> (e.g. 'light.kitchen')

      {.last_updated, .last_changed}

      {.context}                                                {.context_id, .user_id, .parent_id} Unique identifier of context and parent context + user started the change (or None if automatic)

      {.attributes}                                             {.friendly_name, .icon, .entity_picture, .assumed_state, .unit_of_measurement, ... entity specific attributes ...}              assumed_state=boolean (i.e. only approximation, no precise information)

        state_attr('sensor.livingroom', 'Battery numeric')      Accessing custom attributes with space in the attribute name (otherwise 'this.attributes.friendly_name')

 Global

 ------

    states.<domain>.<device_uid>_<entity> {.state, ...}         - See state object above. 

      states('sensor.0x00158d0006c667fa_pressure')              - The '.state' property is better access this way (no error if not set)

      state_attr('sensor.0x00158d0006c667fa_pressure', '.friendly_name')

      is_state('entity', 'state')                               - Checks if entity is in specified state

      is_state_attr('entity', 'attr', 'value')                  - Checks if attribute is set to the specified value

    device

      device_entities(device_id)                                - returns a list of entities that are associated with a given device ID

      device_attr(device_or_entity_id, attr_name)               - returns the value of attr_name for the given device or entity 

      is_device_attr(device_or_entity_id, attr_name, attr_value) 

      device_id(entity_id)                                      - returns the device ID for a given entity ID or device name

    area

      area_entities(area_name_or_id)                            - returns the list of entity IDs tied to a given area ID or name

      area_devices(area_name_or_id)

      area_name/area_id(lookup_value)                           - returns the area name or id for a given device ID, entity ID, or area ID/name

 

 

Events

======

    call_service                                                - Service is called on the object. E.g. turn_on on the light. Also scripts, or automation (enable scene).

    state_changed                                               - State in the state machine is changed

    automation_triggered

    script_started

 

 

Automation:                                                     - Trigger (events or state-changes), Condition (states), Action (services). 

==========                                                      Templates to get properties from trigger event and use it for parametrization.

  automation:

    trigger_variables:                                          - Set some global variable which can be used in templates

        room: "living_room"

        node: "ac"

  

  - mode: single | restart | queued | parallel                  - What to do if another instance of automation is triggered (cancel new instance, stop current instance, execute both sequentially, or in parallel)

    max: 25                                                     - Number of queued/parallel instances (defaults to 10)

    max_exceeded: silent                                        - Level of message to report that too many instances are scheduled in parallel

 

    trigger:                                                    - Multiple triggers are supported (at least one should fire)

      - platform: event                                         - Type of trigger. Events are raw building blocks

        id: "trigger_id"                                        - Referenced from conditions, actions.. Does not need to be unqiue, multiple triggers can be referenced if they share the id. 

                                                                Also multiple ids can be assigned (list)

        enabled: false

        event_type: "custom_event"                              - Triggers if single event is processed

        event_type:                                             - Triggers if any of events is processed

            - custom_event1

            - custom_event2

        event_data:                                             - Triggers only if specific data is associated with event

            state: "on"

        context:

               user_id: ...

 

      - platform: homeassistant

        event: start | shutdown

 

      - platform: mqtt          

        topic: "hall/switch/ac"                                 - MQTT topic, check e.g. with MQTT Explorer

        topic: "{{ room ~ '/switch/' ~ node}}"                  ... Templating example... (Variables defined in 'trigger_variables' section)

        payload: "on"                                           - Optional. Checks that message payload (receieved on 'hall/switch/ac') is equal to the specified value.

        value_template: "{{ value_json.state }}"                - Used in combination with payload. Checks that  message received on 'hall/switch/ac' is valid JSON, with a key 'state'="on"

        encoding: "utf-8"

        

      - platform: numeric_state                                 - Fires only once, but will fire again, once the value has left the defined range and enters it again. 

        entity_id: sensor.temperature                           - Will trigger when 'state' of the entity is changed.

        attribute: attribute_name                               - Alternatively (if specified), will trigger when the value of the given attribute for the given entity changes..

        value_template: "{{ state.attributes.value - 5 }}"      - Alternatively (if specified), triggers when the value given by this evaluated template changes.

        above: ## | sensor.inside_temperature                   - Numeric value can be specified or another sensor could be referenced.

        below: ##

        for: "00:00:30"                                         - Triggers only if condition has been true for the specified time

 

      - platform: numeric_state                                 - Triggers when it is dark outside

        entity_id: sun.sun

        attribute: elevation

        below: -4.0

 

      - platform: state                                         

        entity_id: light.office                                 - By default triggers if state of entity changes or any of associated attributes

        to:                                                     .. (without value) only triggers on state changes

        for: "00:00:30"                                         .. and the changed state (whatever it is) is unchanged for 30 seconds

 

        to: "on"                                                - Triggers if state of light.office changes to "on" (could be also a list)

        for: "00:00:30"                                         .. and stays "on" for 30 seconds

 

        from: "on"                                              - Triggers once state changes to anything else from "on" (should be on first)

        for: "00:00:30"                                         .. and has not returned to "on" for 30 seconds

 

        from: "off"                                             - Exactly changes from 'off' to 'on'

        to: "on"                                                

 

        not_from: "on"

        not_to: "off"

 

      - platform: tag

        tag_id: A7-6B-90-5F                                     - Triggers when NFC tag scanned

        device_id: 0e19cd3cf2b311ea88f469a7512c307d             .. By a specific device

 

      - platform: template                                      - Triggers if template evaluates to true

        value_template: "{% if is_state('device_tracker.paulus', 'home') %}true{% endif %}"

        for: "00:01:00"                                         .. trigger if template remains true for a hour (polled once per minute, unless refer entity generating events)

 

      - platform: time

        at: "15:32:00" | sensor.phone_next_alarm                - Triggered at specified time which is given or taken from referenced entity [ also accepts a list ]

 

      - platform: time_pattern

        hours|minutes: 5 | /5                                   - Cron. Triggered at xx:05 or every 5 minutes

 

      - platform: calendar                                      - Triggers when the specified event in calendar starts or ends

        event: start | end

        entity_id: calendar.light_schedule

 

      - platform: zone                                          - Location based triggers

        entity_id: person.paulus

        zone: zone.home

        event: enter | leave

 

      - platform: webhook

        webhook_id: "hook_id"                                   - curl -X POST -d '{ "key": "value" }' https://smartpi:8123/api/webhook/hook_id         (Also PUT/HEAD requests, but not GET)

                                                                hook_id should be uniq and hook can be used only in a single automation

                                                                POST data is available in template as {{trigger.json}} or {{trigger.data}} (if JSON is passed, use curl -H "Content-Type: application/json")

        

  condition:                                                    - Additional Checks

    - or | and:

      - condition: numeric_state | ... (see triggers)

        attribute: elevation

        below: 4

      - condition: "{{ state_attr('sun.sun', 'elevation') < 4 }}"

      - ...

 

  action:                                                       - See script syntax for details, here few samples only

    - service: light.turn_on

      target:

        entity_id: light.kitchen                                - also lists are supported

      data:

        brightness: 150

        rgb_color: [255, 0, 0]

 

    - condition: "{{ }}"                                        - follwoing actions skipped if condition is not true (also could be a list of conditions)

 

    - service: scene.turn_on                                    - enable specified scene

      target:

        entity_id: scene.romantic                               - Instead of ID, the scene definition could go bellow

 

    - conditions: [ ]                                           - multiple conditions should match

 

 

Scenes                                                          - Defines a whole set of entities along with state and attributes

======

 scene:

  - name: Movies                                                - One scene defined

    entities:

      light.ceiling: "off"

      light.tv_back_light:

        state: "on"

        brightness: 125

      media_player.sony_bravia_tv:

        state: "on"

        source: HDMI 1

  - name: Standard                                              - Another

    entities:

      light.tv_back_light:

        state: "off"

      light.ceiling:

        state: "on"

        brightness: 125

        color_mode: "white"