I can't understand what's going on YAML! Please help

Hi, I am a software engineer and I know a lot about programming in C, C++ specially, still I’m new with python but I can write a simple software using it. I consider myself a QUITE GOOD programmer and I have a good knowledge when it comes to micro-controllers, sensors, …etc. Stop talking about myself and let me talk about my problem here.

My project is very simple, I’m trying to control the esp8266 to switch a led using a button on the dashboard and thanks to YOUTUBE I DID IT just to test the connection first. The next step was to understand how the things work on the home assistant part, starting by creating a button to the configuration.yaml part and here’s where I got stuck. I went through a couple of examples and tutorials about YAML, home assistant and I didn’t understand the point here.

I mean yes I understand how to write YAML file, but how to write what exactly in home assistant?? What is “platform, entity, name, switch, theme,… etc.” Are those words reserved? What do I need to know so I can design a button to switch the led on/ off for example? And what is the relation between this button and the configuration.yml file? I went through all the examples on the home assistant page, I saw more than 27+ videos on youtube and still I can’t understand how the things work here.

I wish anybody can help me with this and if there any good tutorial to answer my questions it will be very helpful.

I just need a guide here people, please help me

Your question is very vague.

What software are you running on the esp8266?

Have you tried esphome?

I’m sorry for that, I wrote a simple software for the esp8266 to control a led using MQTT, like I said I followed the tutorial just to test the connection between the esp and home assistant and it work just fine.

My next goal was to understand the home assistant part, I mean the steps I did to configure the button and the configuration.yml file, and it seems to me I don’t get it.

I want to know the structure of the YAML file just to create a button for example, what is topic? entity? views? what’s come first topic or entity? … etc. Hope I explained myself clearly this time

Sounds like you’re getting too far under the hood… Maybe Github is the place to look.

I assume you’ve checked out the docs?

Yes I did and I couldn’t fine the answer to my questions there. Any suggestion for me?

So there are integrations like sensor, switch or light. You enable Integrations by writing them in your configuration.yaml like:


Each integration has its own platforms like mqtt which lets you create a custom switch for example:

  - platform: mqtt

You then have to look what options there are for each platform. In my opinion the options are mostly well explained. The order doesn’t matter the indentation does:

  - platform: mqtt
    name: led
    icon: mdi:led-on

is the same as

  - platform: mqtt
    icon: mdi:led-on
    name: led

but this isn’t:

  - platform: mqtt
    name: led
      icon: mdi:led-on

Have you looked at the developer docs?

1 Like

And there’s a blog post about how the UI is implemented:

That was very helpful thanks, but how do I know what I need to add for each integration?
Does that de[end on the platform?

For example consider the following:

# Light
  - platform: mqtt
    name: "Light"
    command_topic: "inLight"
    state_topic: "inLight"
    payload_on: "0"
    payload_off: "1"
    retain: true

The integration here is LIGHT, but what about the others…
What is name? icon in your case? command_topic? state_topic? payload? and retain?
What are all of these?

How did you learn all of these? Is there any proper documentation for that?

Just google homeassistant mqtt light
and everything will be explained under CONFIGURATION VARIABLES

1 Like

It may help thanks

I think most people start by editing in the UI, then looking at the yaml to see what they get.

Or they ask questions. I usually use mdi icons:

icon: mdi:speaker
1 Like

the documentation for each domain (light:, switch:, sensor:, etc) will tell you what options are allowed for each domain and will give brief explanation of what each means.

those aren’t necessarily HA specific (the words are but the concepts aren’t)

that relates to the mqtt portion of the device functionality itself.

if you are creating mqtt devices you will need to figure those out yourself.

but then the documentation for mqtt light will tell you how they interface with HA.

Thank you for your help, I will go through the documentation again and I hope at the end I build something awesome.