Is there a Language Reference?

I’m new to Home Assistant. I am now beginning to write scripts, automations etc. Is there a language reference somewhere? For example, in an automation, one has an “action”. What are the available options under “action”, data, service etc. I see data and service in the simple automation script made via the gui, but is there a language reference that would tell me all the possible automation action fields available/possible? I tend to prefer script via a text editor versus use gui tools and i’m seeking to learn. Similar question, why is platform a list? I can’t seem to find this type of information in one place, rather I look at several examples to try and decipher the options. Can someone point me to a language reference or give me some pointers as to how I get a better sense of the overall scope available when working with scripts, automations, scenes, etc.? Thanks in advance.

The automation docs are there, along with all the other things you need.

Once you’ve read the docs that should cover what you’re looking for, though a lot of the actions relate to integrations.

I assume you’ve found https://www.home-assistant.io/docs/ :slightly_smiling_face:
One of the issues with what you are looking for, is that there are (currently) 1615 different integrations, created by different people for diverse purposes and actions for, say, a light are different to those for, say, a car! If you find the integration (https://www.home-assistant.io/integrations/) it should tell you what services are available for that integration.

Thank you; much appreciated. Therefore, to see which items are required or available, I would look to the “integration” documentation even though the “action” field is specific to home assistant. I will follow that approach.

Thank you. Following this approach, I still get “stuck” when seeking to determine how I pass a custom message based on a MQTT subscribe topic, through a script to a notify message via gmail. Am I supposed to look at the MQTT “integration”? Currently, my automation passes the MQTT “topic” versus the message in the script, perhaps I need to populate the “data” field in the automation. ???

Can you give a more concrete example? You shouldn’t really need to write to a mqtt topic. Mqtt is the glue to a number of integrations. Use the service for the particular integration.

Or I may be misunderstand you completely, hence the request for a more concrete example :slight_smile:

Sure. As I’m learning Home Assistant, I’ve had a hard time finding documentation, sure, I can review the documentation but it’s not clear how it all “ties together”. If there is a data field in yaml, what are the allowable fields (title, message, etc.). In this instance specifically, I have (by nature of my learning process) the following:

  1. An Arduino-based sketch with uses an NodeMCU and script to publish to a specific topic (“test/test1”) the message “Button Pushed” when a mechanical button is pushed
  2. I have a Test script which simply calls a “notify” service which sends an email to my Gmail account

In a “next step” toward the goal of getting an SMS text on my phone when the Arduino button is pushed, I’m looking to tie these mini-test projects together to create the following (I recognize I may not need all these in the end, but I’m in the learning/experimenting phase):

  1. Have the push bottom on my Arduino project publish “Button Pushed” to the MQTT broker
  2. Have the Automation in Home Assistant act upon this MQTT topic (i.e. Automation is platform: mqtt topic: test/test1)
  3. In this learning experiment, I want the Automation to call my existing Script which calls a Notify service to send a text via Gmail SMS, HOWEVER, I’d like to send a custom message versus the “Button Pushed” payload from the originating mqtt message. Therefore, do I specify the message in data elements of the Automation, Script or Notify yaml? Right now, it appears the mqtt payload supersedes everything but it doesn’t seem like that should be the case (seem like I should be able to provide a data message somewhere).

Thanks, some yaml provided below:
automation.yaml

- id: '1595082470131'
  alias: Send.Notify.GmailText
  description: Send a text via Gmail SMS
  trigger:
  - platform: mqtt
    topic: test/test1
  condition: []
  action:
  - data:
    messsage: "test/test1 has been triggered by a button press"
    title: "Button Press"
    service: script.1592538793555

scripts.yaml

'1592538793555':
  alias: script.buttonpress2
  sequence: 
    - service: notify.myGmailAlert
      data:
        message: buttonpress2
        title: MQTT Button Press      

notify.yaml

  - name: myGmailAlert
    platform: smtp
    server: smtp.gmail.com
    port: 587
    sender: !secret myusername
    sender_name: My HomeAssistant Site
    starttls: 1
    username: !secret myusername
    password: !secret mypassword
    recipient: !secret myrecipient

I think you have taken a wrong turn. The button should be implemented as a binary_sensor.

Also I think the notify integration will be called notify.mygmailalert not notify.myGmailAlert

My ability with templating will not solve your problem, but there are some smart people who should be able to help. @123 or @pnbruckner come to mind.

Unfortunately a lot of the more esoteric documentation is to be found on the forum :slight_smile:

The action section of an automation is the same as the sequence section of a script. They both use HA’s script syntax. This page tells you the types of actions you can include in a script/automation. (Teaser: there will be a couple more types of actions in the 0.113 release: repeat & choose.)

When it comes to calling a service, you’ll probably need to check the corresponding “integration” docs for what services they each support.

A service call, whether in a script or automation, takes optional data. That data is grouped under the data: keyword or the data_template: keyword. (One exception is entity_id. It can either be under data:, or at the same level as service: & data:. That is just a convenience. If you provide it at the same level as service:, internally it will be moved under data:. So if that confuses you, just always put it under data:.)

Use data: if all the data is fixed. Use data_template: if any of the data values need to be specified by a template.

So, in your automation you need to take the payload and “pass it” to the script. You get the payload via trigger.payload (see MQTT trigger data.)

- id: '1595082470131'
  alias: Send.Notify.GmailText
  description: Send a text via Gmail SMS
  trigger:
  - platform: mqtt
    topic: test/test1
  condition: []
  action:
  - data_template:
      message: "{{ trigger.payload }}"
      title: "Button Press"
    service: script.1592538793555

Then in the script you use the passed in data:

'1592538793555':
  alias: script.buttonpress2
  sequence: 
    - service: notify.myGmailAlert
      data_template:
        message: "{{ message }}"
        title: "{{ title }}"

Of course in this scenario you don’t really need the script as an intermediary:

- id: '1595082470131'
  alias: Send.Notify.GmailText
  description: Send a text via Gmail SMS
  trigger:
  - platform: mqtt
    topic: test/test1
  condition: []
  action:
  - service: notify.myGmailAlert
    data_template:
      message: "{{ trigger.payload }}"
      title: Button Press

I kind of had to guess what you wanted to do with the payload, but hopefully this gets you started.

nickrout, thank you, I appreciate the input.

Phil, …perfect, this will get me going! Again, thanks very much.