Config syntax

Wow! What a great bit of software HA is. Coming from OpenHab this is a blessing. Great interface and reliable system.

First question, as a software dev myself albeit in less fashionable embedded realtime systems, I am getting confused with configruation.yaml content. Terms such as component and entiry and integration and platformseem to be used either in contradiction, intermittently, or both.

Take this example:

…called a component here, but switch is elsewhere referred to as an integration - oh, and also a service. When one sees switch in a configuration.yaml, which one is it and why?

And this example:

…mqtt is a platform here , but it also exists as an integration and in some docs - referred to as a component .

How to conceptualise this by reading a detailed configuration.yam is proving difficult.
There is devices,services,entities - how are these populated in the config.

it’s all quite confusing. Can someone clarify please what the syntax/glossary is for a configuration.yaml - and before you post a link to the docs, I’ve read them and that hasnt helped - I even used examples of doc pages in this post :slight_smile:

What would be really helpful is a syntax tree (something like Backus-Naur - or anything really) that would describe what the syntax is for a compound configuration.yaml consisting of

  • Components
  • Integrations
  • Platforms
  • Services
  • Devices
  • Entities
  • Groups
  • Parameters
    etc etc

I dont know, maybe I’m thinking something like:

configuration.yaml  = [ {entry } ]
entry = ( integration | component  | service | device | entity )
integration = integration_name , colon_char, new_line , arguments_block 
new_line = "\r\n"
arguments_block = {indent , argument}
indent = white_space_char , white_space_char
argument =  { collection | key_value_pair } 
collection = "-" , { argument } 

and so on , you get the idea. forgive the BN correctness for HA , it’s just and example

I dont know what the syntax is but it would really help if I did and I guess others who want to craft their own configuration.yaml would also benefit.


I’d write the tree and publish it on here if I could understand HA a bit more please.

obvious , but no cigar Tom. Of course, I read that, I wouldnt be here otherwise - if it answers the question, which it does not. Read carefully :slight_smile:

Maybe the dev architecture docs may help you get a better understanding.

It answers this question:

Each of those terms are explained with links to examples.

Yeah, I feel your pain.

MQTT is a thorny one.
HA supports mqtt natively so when you call a service under mqtt it is under the MQTT platform
But you must install mqtt as a integration for it to become ‘native’
Though mqtt services may be external to HA but still callable (is that even a word ?)

You basically have to remember that HA is a large body of work built by many individuals, their terminology varies as does the documentation that supports it. Of late there has been a great effort to standardise the documentation but that (if anything) has highlighted the differences in implementation methodologies. For instance some entities support templating of certain attributes whereas others don’t. (trying to think of them off the top of my head but without reference to my config I’m vague)

Regardless, there are ‘wrinkles’ you have to learn and generally we learn what works in which circumstances and basically copy that - then adapt it. Once you get that you can experiment and expand your feel for the syntax. Examples are the best way to learn, and I find most code to be explorable and ‘moderately’ easy to adapt.

Given your background I would recommend you first play with basic automations. Turning a light on and off, delays, events etc. But as soon as possible move on to packages, where a package file can contain ALL the code required for a particular function/room/subset for instance I have a package file for my waste/recycling collection indicator which I could just give to someone else, they build the hardware, name the entities and it should just run. It contains all the input booleans, input numbers, binary sensors, customisations, zones, scripts, automations etc. Rather than have to visit individual files for all those entities.

Edit: IE its an encapsulated learning example

1 Like

you cant read then !
(hint: syntax, tree, bnf, etc.) Never mind Tom. Don’t worry about this thread :slight_smile:

Please keep it civil guys

Ah-ha @Burningstone ; that will do nicely. Have to admit to not reading dev pages as I am not a dev in HA. This content is nevertheless useful to a user perspective in my view. Thanks pal

I tried , but he insists on repeating himself and I [thought I] had nicely declined. I shall leave it there.

perfect @Mutt , really helpful and using good examples of examples.

YES ! “callable” is a word certianly in my 35+ years developing system software. Another word I love was immutable - my wife calls me that too!

EDIT: I now recognise [thanks] that HA was built up from a foundation and development coming from different disciplines using various nomenclature. It’s hard to document that in the absence of a complete software harmonization across the board - which will never happen, we are where we are. Thanks once agai for the deailed explanation

Well here is the package I was talking about, if is is of interest, not necessarily for the actual use but as an example.

yep, that’s great. looking into your work I will increase comprehension so thank you . You’re pulling out all the rabbits today pal ! Love the engineering in confied spaces work too !:-):slight_smile:

I’m also not a dev, just stumbled on this page by accident once and thought that it was really helpful.
I can also recommend taking a look at config of other people on Github. Some of them are documented pretty well. This page is a nice collection of HA configs, interesting topics etc.
And here my repo, which is also more or less documented.

Grüß Gott !

(Ich spreche ein bisschen Deutsch. Arbeitet für eurofighter (EF-GmbH) in München. und jetzt auf englisch es tut mir lite)

You humble yourself. your Git repo has some creative code. I’ would deem that to be software developing, particularly using Python which is an extensive feature rich language. The code is well designed. When looking at the dishwsher automation , I was intriqgued to figure out how a dishwasher is going to notify you of events/state. So went into your code and noted that you must be using some kind of decice measuring power consumption of the washer which is dependent upong programme/state. Very clever.

You home automation is far more than I use or would need. Nevertheless, it is a good repo for studying the capabilities of HA and integrations.

Perhaps you can explain this for me please…

It discusses an integration and the add-on.
What is the difference between the MQTT Integration and a MQTT Broker add-on. In the example code:

# Example configuration.yaml entry

Is mqtt here the integration or the add-on or the platform or a service?
Is broker an entity or device or something else?
What does the code actuall mean? and what other examples of “mqtt” are there that mean something different.

Also, I setup my broker just as above, but running my own client from here, for my Enrgenie devices.

When I start HA it all works fine and I can control the energenie but HA logs seem to be complaining about the port already being used??

Feb 26 23:49:44 pi hass[10164]: 2020-02-26 23:49:44 INFO (MainThread) [homeassistant.setup] Setup of domain fan took 0.0 seconds.
Feb 26 23:49:44 pi hass[10164]: 2020-02-26 23:49:44 ERROR (MainThread) [] Broker startup failed: [Errno 98] error while attempting to bind on address ('', 1883): address already in use
Feb 26 23:49:44 pi hass[10164]: 2020-02-26 23:49:44 INFO (MainThread) [transitions.core] Exited state starting
Feb 26 23:49:44 pi hass[10164]: 2020-02-26 23:49:44 INFO (MainThread) [transitions.core] Entered state not_started
Feb 26 23:49:44 pi hass[10164]: 2020-02-26 23:49:44 ERROR (MainThread) [homeassistant.components.mqtt.server] Error initializing MQTT server
Feb 26 23:49:44 pi hass[10164]: Traceback (most recent call last):
Feb 26 23:49:44 pi hass[10164]:   File "/srv/homeassistant/lib/python3.7/site-packages/hbmqtt/", line 276, in start
Feb 26 23:49:44 pi hass[10164]:     loop=self._loop)
Feb 26 23:49:44 pi hass[10164]:   File "/usr/lib/python3.7/asyncio/", line 114, in start_server
Feb 26 23:49:44 pi hass[10164]:     return await loop.create_server(factory, host, port, **kwds)
Feb 26 23:49:44 pi hass[10164]:   File "/usr/lib/python3.7/asyncio/", line 1378, in create_server
Feb 26 23:49:44 pi hass[10164]:     % (sa, err.strerror.lower())) from None
Feb 26 23:49:44 pi hass[10164]: OSError: [Errno 98] error while attempting to bind on address ('', 1883): address already in use
Feb 26 23:49:44 pi hass[10164]: During handling of the above exception, another exception occurred:
Feb 26 23:49:44 pi hass[10164]: Traceback (most recent call last):
Feb 26 23:49:44 pi hass[10164]:   File "/srv/homeassistant/lib/python3.7/site-packages/homeassistant/components/mqtt/", line 48, in async_start
Feb 26 23:49:44 pi hass[10164]:     await broker.start()
Feb 26 23:49:44 pi hass[10164]:   File "/srv/homeassistant/lib/python3.7/site-packages/hbmqtt/", line 297, in start
Feb 26 23:49:44 pi hass[10164]:     raise BrokerException("Broker instance can't be started: %s" % e)
Feb 26 23:49:44 pi hass[10164]: Broker instance can't be started: [Errno 98] error while attempting to bind on address ('', 1883): address already in use
Feb 26 23:49:44 pi hass[10164]: 2020-02-26 23:49:44 ERROR (MainThread) [homeassistant.components.mqtt] Unable to start embedded MQTT broker
Feb 26 23:49:44 pi hass[10164]: 2020-02-26 23:49:44 INFO (MainThread) [homeassistant.setup] Setup of domain mqtt took 0.5 seconds.
Feb 26 23:49:44 pi hass[10164]: 2020-02-26 23:49:44 ERROR (MainThread) [homeassistant.setup] Setup failed for mqtt: Integration failed to initialize.

However, as I say, everything is actually, working.
My head hurts.Text

No need to be sorry, I use English almost everyday for work, so it doesn’t really matter for me :wink:
Are you living outside of Germany, but working in Germany?

I’ll try to explain the MQTT topic.
The MQTT broker is like the “server” part of the MQTT ecosystem. The clients publish/subscribe to topics on the MQTT broker. You can setup the MQTT broker on any machine you like, some do it on the same machine as HA is running, some on other machines. You can either setup the MQTT broker yourself or if you are using Home Assistant (formerly called you can also use the MQTT broker add-on. Take a look on the docs for add-ons here.

The MQTT integration is then used to connect HA to the MQTT broker, so that HA can as well publish/subscribe to the topics on the MQTT broker. HA is then also a client to the MQTT broker.

I hope this explanation helps, let me know if something is unclear or needs further explanation.

I’m currently working on a bigger project, where I setup my system from scratch and document every detail on how I configured it etc. and the files will then also be on this repo. I do this to help other HA users to get started or they might find some config in there that solves some of their issues. I also do this for myself in order to have a complete documentation to set everything up from scratch if needed (probably not as I have a I would say “decent” backup system in place).

Ah, I understand now. The concepts of integration, add-ons, platform etc were confusing. For example the docs mention:
mqtt service
mqtt add on
mqtt integration
mqtt client (entity?)
very confusing.

So it appears that I have installed the mqtt integration (correct) but also installed the mqtt add-on (incorrect). I run my own mqtt client that is using mosquitto services as the broker, and the mosquitto capability plus the client is all in one executable that runs as s systemd service within a Raspbian Lite OS running HA inside a python venv.
I shall remove the mqtt add on and that will heopfully remove the mqtt errors in the log file , and also the use of resources not needed.

Vielen dank.