How to add Shelley devices to HA?

I recently bought a few Shelly devices (bulb, plug, rgbw wifi cntroller) and they are great! I can “manage” them via MQTT from the “developers tools” tab, by sending “on/off messages”. I now want to go one step further and integrate the devices into HA scripts and scenes. But how do I do that, I don’t see the devices in HA? I searched and found this post Shellies Discovery Script. Is this indeed the way to go, or can devices these days be added more easily in HA?

If you want to use them with stock firmware, that is the way to go. My shelly 1s are all flashed with tasmota, that is an alternative.

If you want to use MQTT with stock firmware you can add Shelly via manual configuration or use the discovery script.


I want to add the devices manually to fully understand what is happening, and I don’t have that many devices (yet).

I have read the following documentation several times: Shellies Discovery Script

But it is not clear to me where I have to configure the Shelly devices. I assume not in configuration.yaml, or is that indeed the right place?

It is also not clear to me what to configure of the devices for HA to “pick them up” and make them available in de “configurations - devices - tab”.

A (reference to) simple example - for example of a shelly plug - would be very helpful.

Many thanks in advance,

Ok, first off all, manual mqtt configured devices will never show up in the “configurations - devices - tab”. (Never is a big word, I still hope someday in the future it will)

If you want a good example, install mqtt.fx or mqtt explorer, subscribe to #, and run the shellies discovery script. You should see the configuration message in either mqtt.fx or mqtt explorer.

Thank you for your response. The last few days I experimented with my shelly devices in combination with the HA MQTT broker. I saw messages and statuses coming in (listening with #) and I have published messages to switch devices on and off. I assume that you refer to that with installing “mqtt.fx” and / or “mqtt explorer” - correct? So till some extend I understand topics and payloads. You advise me to use the Python script from Bieniu. Befor I do so a check question: will the devices in that case appear in the “configurations - devices - tab”? It is my understanding that that is necessary if I want to integrate the devices into scripts, scenes and automations. Is that correct?

Manual configured mqtt devices show under entities, but not under devices. To show under devices, they need to be discovered. You can create your own discovery messages (I did that for a lot of my sonoff rf bridge and rflink esprflinkmqtt devices) or simply use the shellies discovery script.

Food for thought : devices vd entities …

Tonight, I’m going to try to install the discovery script.

Then I’ll see further from there

I think I’m almost there.

First I installed HASC, that went well.
Then added “python_script:” in configuration.yaml
And searched for Shelly => in the HACS tab under Integration =>
Found “ShellyForHass (Shelly integration)” and installed it

But …
I don’t see any Shelly devices in the “Configuration-devices-tab”
And received the following notification.


Searched for a while, but I am stuck now…
What goes wrong?

Any help / assistance will be very much appreciated.

ShellyForHass is not Shellies Discovery. Shellies Discovery is in Python Script section:

Thanks Bieniu, I work on it tomorrow. Now it’s time for bed, the alarm goes off early tomorrow morning. I can’t remember seeing a Python script section in HACS (does that ring a bell?) , but I’ll double check it tomorrow. Ko

I managed to install the Shelly Discovery script and it is now available in HA as a service.

Now I want to use the script. I understand that some configuration is needed.

In which configFile should I do this, in “automations.yaml” or in another file?

And what is the next step, starting the script “python_script.shellies_discovery” in the “SERVICES tab” at “Developers Tools”?

I guess it’s almost done just need a little bit more help to finish it :wink:

Next step is restart HA. Don’t run the script manually.

Followed your instructions.

Notification after reboot:


Two entries in the logFile:

2020-03-09 22:21:23 WARNING (MainThread) [homeassistant.loader] You are using a custom integration for hacs which has not been tested by Home Assistant. This component might cause stability problems, be sure to disable it if you do experience issues with Home Assistant.

2020-03-09 22:21:30 ERROR (MainThread) [homeassistant.config] Invalid config for [automation]: [automation] is an invalid option for [automation]. Check: automation->automation. (See /config/configuration.yaml, line 13).

Snippet of configuration.yaml


High lighted rule is line 13 as mentioned in the errorLog.

What is wrong here, should I modify this line, or …?

Guys, as far as I understand, OP asked for as much generic control as possible over shelly devices. You offers various solutions, mostly not direct nor reliable enough. I could understand that in case it would be fire and forget, providing all needed features not requiring HA restarts at the same time. But it’s not the case(I did wish it myself, tried it and get rid of it)

I know Bieniu did great work with his script, but it’s something which works on top of mqtt discovery. The latter is not mature enough enough IMO. It requires system restarts for particular operations (ie removing entities, renaming them etc). At some point I was restarting HA more often than when setting Shelly entities in configuration.yaml. Maybe it works as proof of concept but in reality it means too much hassle, no real income.

Forgive me such attitude, but this is my experience speaking after installing more than 20 Shelly devices. And I think posts above also support my standpoint pretty well.

At the end I ended up with manual configuration of Shelly devices. It requires HA restart every time a device is added, removed or renamed, but at least those operations and their results are expected. It’s very important if you experimenting with stuff, sets names (of mqtt topics or entities) to tune up your system etc.

I do use Shelly1, Shelly2.5, Shelly Dimmer and Shelly Socket S.
Currently i have configuration split to different files. But it’s ok to start with the same entries in configuration.yaml

Example Shelly1/Shelly2.5 single switch configuration and Shelly Dimmer (Bedroom 1), both in light domain

  - platform: mqtt
    name: "Pantry"
    command_topic: "shellies/shelly1-pantry/relay/0/command"
    state_topic: "shellies/shelly1-pantry/relay/0"
    availability_topic: "shellies/shelly1-pantry/online"
    qos: 1
    retain: false
    payload_on: "on"
    payload_off: "off"
    payload_available: "true"
    payload_not_available: "false"
    optimistic: false
  - platform: mqtt
    schema: template
    name: 'Bedroom 1'
    state_topic: "shellies/shelly1-sleeping1/light/0/status"
    availability_topic: "shellies/shelly1-cube5/online"
    state_template: '{% if value_json.ison %} on {% else %} off {% endif %}'
    command_topic: "shellies/shelly1-sleeping1/light/0/set"
    command_on_template: '{"turn": "on"{% if brightness is defined %}, "brightness": {{(brightness | float * 0.3882 + 1) | round(0)}}{% endif %}}'
    command_off_template: '{"turn": "off"}'
    brightness_template: '{{ (value_json.brightness | float * 2.55) | round(0) }}'
    payload_available: "true"
    payload_not_available: "false"
    qos: 1
    retain: false
    optimistic: false 

Shelly Plug S power/temp sensor. To control a plug relay, you need to add switch or light configuration (as above)

 - platform: mqtt
    name: "Washing Machine Power"
    state_topic: "shellies/shellyplug-washing/relay/0/power"
    availability_topic: "shellies/shellyplug-washing/online"
    icon: 'mdi:washing-machine'
    unit_of_measurement: "W"
    payload_available: "true"
    payload_not_available: "false"
  - platform: mqtt
    name: "Washing Machine Temp"
    state_topic: "shellies/shellyplug-washing/temperature"
    availability_topic: "shellies/shellyplug-washing/online"
    icon: 'mdi:thermometer'
    unit_of_measurement: '°C'
    payload_available: "true"
    payload_not_available: "false"

BTW my comments above are about MQTT integration of Shelly devices. There is REST based integration available in HACS. But it uses polling which is not what I was looking for. Saying that I cannot comment on this integration due to no experience with it.

1 Like

You used automation: keyword twice.

Ok, modified configuration.yaml.


No more Errors in the log, only this warning => so far so good.

2020-03-10 08:01:42 WARNING (MainThread) [homeassistant.loader] You are using a custom integration for hacs which has not been tested by Home Assistant. This component might cause stability problems, be sure to disable it if you do experience issues with Home Assistant.

No more notifications at HA => also good

I toggled some Shelly devices and see messages coming in => also good

But still no devices in HA => noGood ;-(.

My automation.yaml is as follows:

What is the last (?) step to get the devices discovered?

Something necessary in the services tab …

Or something else?

Assuming everything is set up well. Will the devices be discovered automatically when they start sending messages? And will the configuration in configuration.yaml then dynamically be adjusted?

Remove automation: from file automations.yaml and unhash automation: !include automations.yaml.

Ok, I’m going to do it tonight.

One more question though.


ad1: I remove the #

ad2: do I still need this line, or should it be removed?