This script adds MQTT discovery support for Shelly devices and without configuration it adds entities to Home Assistant.
This is screenshots with Home Assistant Integrations page:
Supported devices:
- Shelly 1 (with external sensors)
- Shelly 1L
- Shelly 1PM (with external sensors)
- Shelly 2 (relays and roller mode)
- Shelly 2.5 (relays and roller mode)
- Shelly 3EM
- Shelly 4Pro
- Shelly Air
- Shelly Bulb
- Shelly Bulb RGBW
- Shelly Button1
- Shelly Dimmer
- Shelly Dimmer 2
- Shelly Door/Window
- Shelly Door/Window 2
- Shelly DUO
- Shelly EM
- Shelly Flood
- Shelly H&T (with or without USB adapter)
- Shelly i3
- Shelly Plug
- Shelly Plug S
- Shelly Plug US
- Shelly RGBW2 (color and white mode)
- Shelly Sense
- Shelly Smoke
- Shelly Vintage
- Shelly UNI (with external sensors)
- Shelly Motion
Prerequisites
This script needs Home Assistant python_script
component so, if you never used it, I strongly suggest you to follow the official instruction and check that python_script
is properly configured and itâs working.
Installation
You can download shellies_discovery.py
file and save it in <config>/python_scripts
folder or install the script via HACS.
You wonât find Shellies Discovery in the HACS Integrations section, nor add it as a custom repository. You must have a properly configured python_script
component to be able to install the script from the HACS Automations section.
You have to add python_script
component to your configuration.yaml
file:
# configuration.yaml file
python_script:
Repository: https://github.com/bieniu/ha-shellies-discovery
How to debug
To debug the script add this to your logger
configuration:
# configuration.yaml file
logger:
default: warning
logs:
homeassistant.components.python_script: debug
homeassistant.components.automation: info
Troubleshooting checklist
- correct MQTT configuration in Home Assistant with
discovery
enabled - same
discovery_prefix
in Home Assistant configuration and in script configuration - Shellies firmware updated to current version
- Home Assistant updated to current version
- enabled MQTT in Shellies configuration
- you canât manually run the
shellies_discovery.py
script ('trigger' is undefined
error)
Shelly device name
The script supports Shelly devices with non-standard names ( Internet & Security
-> Advanced - developer settings
-> Custom MQTT prefix
in the Shelly WWW panel). If you want to change the name of the Shelly device, you must first remove the device from Home Assistant ( Configuration
-> Integrations
-> MQTT
-> Device -> Remove
). Otherwise, all device entities will be duplicated.
Minimal configuration:
# automations.yaml file
- id: shellies_announce
alias: 'Shellies Announce'
trigger:
- platform: homeassistant
event: start
- platform: time_pattern
hours: "/1" # Modifying this if you are using Shelly Motion can drain your device's battery quickly.
action:
service: mqtt.publish
data:
topic: shellies/command
payload: announce
- id: 'shellies_discovery'
alias: 'Shellies Discovery'
mode: queued
max: 999
trigger:
platform: mqtt
topic: shellies/announce
action:
service: python_script.shellies_discovery
data:
id: '{{ trigger.payload_json.id }}'
mac: '{{ trigger.payload_json.mac }}'
fw_ver: '{{ trigger.payload_json.fw_ver }}'
model: '{{ trigger.payload_json.model }}'
Custom configuration example
# configuration.yaml file
python_script:
# automations.yaml file
- id: shellies_announce
alias: 'Shellies Announce'
trigger:
- platform: homeassistant
event: start
- platform: time_pattern
hours: "/1" # Modifying this if you are using Shelly Motion can drain your device's battery quickly.
action:
service: mqtt.publish
data:
topic: shellies/command
payload: announce
- id: 'shellies_discovery'
alias: 'Shellies Discovery'
mode: queued
max: 999
trigger:
platform: mqtt
topic: shellies/announce
action:
service: python_script.shellies_discovery
data:
id: '{{ trigger.payload_json.id }}'
mac: '{{ trigger.payload_json.mac }}'
fw_ver: '{{ trigger.payload_json.fw_ver }}'
model: '{{ trigger.payload_json.model }}'
discovery_prefix: 'hass'
qos: 2
shelly1-AABB9900:
relay-0: "light"
ext-temperature-0: true
ext-temperature-1: true
ext-temperature-2: true
force_update_sensors: true
shelly1pm-aabb9911:
ext-temperature-0: true
ext-humidity-0: true
longpush_off_delay: false
force_update_sensors: true
shellyswitch-123409FF:
relay-0: "fan"
relay-1: "light"
shellyswitch-123409cc:
relay-1: "fan"
shellyswitch25-334455AA:
mode: "roller"
position_template: "{{ '{% if value | float < 30 %}0{% else %}{{ value }}{% endif %}' }}"
set_position_template: "{{ '{%if position | float < 30 %}0{% else %}{{ position }}{% endif %}' }}"
shellyplug-s-CCBBCCAA:
relay-0: "light"
force_update_sensors: true
shellyht-11AA00CCDD:
force_update_sensors: true
expire_after: 500
shellyht-11AA00CCEE:
powered: "battery"
shellyht-11AA00CCFF:
powered: "ac"
shellyrgbw2-AA123FF32:
mode: "white"
shellyrgbw2-AA123FF84:
mode: "rgbw"
shellyem-BB23CC45:
force_update_sensors: true
ignored_devices:
- shelly1-DD0011
- shellyem-EECC22
Battery powered devices
For battery powered devices, the script requires you to set the value of 12h for sleep_mode.period
or to configure expire_after
yourself.
Donât send announce
topic more than once an hour if youâre using Shelly Motion! This can quickly drain your deviceâs battery.
How to use device automation triggers?
key | optional | type | default | description |
---|---|---|---|---|
discovery_prefix |
True | string | homeassistant |
MQTT discovery prefix |
qos |
True | integer | 0 |
MQTT QoS, you can use 0 , 1 or 2
|
ignored_devices |
True | list | None |
list of devices to ignore |
key | optional | type | default | possible values | description |
---|---|---|---|---|---|
relay-<NUM> |
True | string | switch |
switch , light , fan
|
component to use with the relay number NUM
|
ext-temperature-<NUM> |
True | boolean | false |
true , false
|
presence of temperature sensor number NUM
|
ext-humidity-<NUM> |
True | boolean | false |
true , false
|
presence of humidity sensor number NUM
|
force_update_sensors |
True | boolean | false |
true , false
|
force update for sensors |
longpush_off_delay |
True | boolean | true |
true , false
|
off delay (3 sec) for longpush binary sensors |
mode |
True | string |
white , rgbw , relay , roller
|
white or rgbw for ShellyRGBW2, relay or roller for Shelly2/Shelly2.5 |
|
powered |
True | string | battery |
ac , battery
|
ac or battery powered for ShellyHT |
expire_after |
True | integer | 43200 | expire after for battery powered sensors in seconds |
If you already have Shellies configuration before using the script, you should delete it. After installing the script and adding automations, run Shellies Announce
automation or restart Home Assistant twice.