Shellies Discovery Script

Share your Projects! Scripts
Tags: #<Tag:0x00007fc420a6d808>
#1

This script adds MQTT discovery support for Shelly devices and without configuration it adds entities to Home Assistant.

Buy Me A Coffee

This is screenshots with Home Assistant Integrations page:

shellies-integration
shellies-integration1189×433 63 KB

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?

trigger
trigger1116×771 1.62 MB

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.

29 Likes
Shelly H&T with MQTT
Shelly factory firmware configuration with Home Assistant
Shelly 2 as roller shutter with percentage
Shelly 1 will topic and message
Shelly Dimmer with MQTT
Shelly 2.5 mqtt integration
How to add Shelley devices to HA?
Shelly 1 state without changing the relay
Configuring Shelly EM Energy Meter
Integrating Shelly using MQTT doesn't work
MQTT to HA issues
MQTT sensors for MQTT Sensor integration
Shelly1 Integration through MQTT - problem
MQTT: discovery with shelly devices?
Shelly Flood
Solved: Mqtt turns me mad
Shelly H&T unavailable data
Shelly Cloud - new Component? How to implement it? API is available
REST switch not showing up
MQTT audio discovery help
How to add Shelley devices to HA?
Shelly Cloud - smooth dimming over MQTT using deconz
Make a dumb doorbell smart with Shelly 1
Native MQTT and Shelly
WTH doesn't MQTT integration have an editor to add devices?
Infrastructure, cabling & design
ShellyForHass custom component
#2

New version: 0.0.2

Changelog:

  • add support for Shelly Plug and Shelly4Pro
#3

Hi!

Just tried this script with my shelly-plug.
Both the switch and the power-sensor is added as entities under MQTT integration, but I think the power-sensor is not subscribing to the correct state_topic.

Ever since I included it with the script instead of the manual config, I get state unknown for the sensor.

I am new to Python, so I am not fully following the syntax, but seems that you are making the sensor subscribe to the wrong topic. Correct topic would be:
shellies/shellyplug-7BD83C//relay/0/power.

It is missing the relay-number.
With the current script, the sensor subscribes to:
shellies/shellyplug-7BD83C/relay/power

If i publish to that topic, the sensor updates directly.

As mentioned, I have never worked with python, so not 100% sure on how to get the syntax correct. Could you please update it?

On a related topic, is there any way I can review what settings the entities were created with? I am not finding the config-entries anywhere in the files, so the troubleshooting was a bit more guesswork than would have been nessecary if I could have reviewed the entity topics manually.

Thanks!

#4

Yes you are right. I only have Shelly2 and it send topic without relay number. I will correct the script. Does Shelly Plug send correct data in topic energy?

#5

Hi
Energy is published in “shellies/shellyplug-XXXXXX/relay/0/energy”
with unit [10 * Wh] seems like a very strange energy-unit.
So if you do end up adding it, please convert it to kWh directly, seems confusing to use a non SI unit of 10Wh

#6

For info,
Looking at the API-documentation, it appears that the 4pro is using the same logic with */0/power as the plug

https://shelly-api-docs.shelly.cloud/#4pro-mqtt

#7

Yes, I have read API documentation. Shelly2 for two relays sends power in one topic and doesn’t send energy at all because of issue in firmware. I thought that Shelly Plug and Shelly4Pro have the same issue.

#8

Can you add support for Shelly H/T
image

- platform: mqtt
  name: "HT Dinner  Temp"
  state_topic: "shellies/shellyht-YOUR_ID_1/sensor/temperature"
  unit_of_measurement: '°C'
  device_class: temperature
- platform: mqtt
  name: "HT Dinner  Humidity"
  state_topic: "shellies/shellyht-YOUR_ID_1/sensor/humidity"
  unit_of_measurement: '%'
  device_class: humidity
- platform: mqtt
  name: "HT Dinner  Battery"
  state_topic: "shellies/shellyht-YOUR_ID_1/sensor/battery"
  unit_of_measurement: '%'
  device_class: battery
- platform: mqtt
  name: "HT Dinner  Online"
  state_topic: "shellies/shellyht-YOUR_ID_1/online"

  
- platform: mqtt
  name: "HT Living Temp"
  state_topic: "shellies/shellyht-YOUR_ID_2/sensor/temperature"
  unit_of_measurement: '°C'
  device_class: temperature
- platform: mqtt
  name: "HT Living Humidity"
  state_topic: "shellies/shellyht-YOUR_ID_2/sensor/humidity"
  unit_of_measurement: '%'
  device_class: humidity
- platform: mqtt
  name: "HT Living Battery"
  state_topic: "shellies/shellyht-YOUR_ID_2/sensor/battery"
  unit_of_measurement: '%'
  device_class: battery
- platform: mqtt
  name: "HT Living Online"
  state_topic: "shellies/shellyht-YOUR_ID_2/online"
 
- platform: mqtt
  name: "Shelly Firmware"
  state_topic: "shellies/announce"
  value_template: "{{ value_json.new_fw }}"
  json_attributes:
    - fw_ver  
    - new_fw
    - id
    - mac
    - ip
2 Likes
#9

New version: 0.1.0

Changelog:

  • add developer mode for safe debug
  • fix power sensor topic for Shelly Plug and Shelly4Pro
  • add energy sensor for Shelly Plug and Shelly4Pro
1 Like
#10

@Flanders Please, write whether the sensors are working properly on the new version of the script.
@elRadix Thanks for the configuration. Soon I will add support for ShellyH&T to the script.

1 Like
#11

@elRadix Does ShellyH&T in the announce topic send the unit that is used for the temperature sensor (°C or °F)?

#12

I don’t understand What’s the benefit using this script… Shelly have already mqtt support by default in their fw.
Or with this script we can get more infos that i missed?

#13

You add only the script and two automations to HA configuration, and each Shelly will be added to HA via MQTT Discovery with support for device registry and entity registry.

Screenshot_2019-02-27%20Home%20Assistant
Screenshot_2019-02-27%20Home%20Assistant(1) Screenshot_2019-02-27%20Home%20Assistant(2)

#14

Hi!
Forgot to post feedback after testing yesterday, sorry.

Tested it, and works fine. Power sensor is added with correct topic and is now working.
The old non working power sensor is still there though. not sure if it was re-added, or if I failed to delete it completely.

image

The 2nd and 3rd I re-named and are the working ones, the first one is the sensor with the wrong topic that gets re-added even after deleting it in the entity-registry.

#15

To remove the incorrect power sensor you have to:

  • Send empty message to MQTT broker with topic shellies/shellyplug-7BD83C/relay/power and retain flag. You can use this command mosquitto_pub -h MQTT_BROKER_IP -p MQTT_BROKER_PORT -u MQTT_USER -P MQTT_PASSWORD -r -t 'shellies/shellyplug-7BD83C/relay/power' -m ''
  • Remove sensor entity from entity registry. You can do it manually from file .storage/core.entity_registry (not recomended) or from Entity Registry in frontend (Settings -> Entity Registry).
  • restart Home Assistant

What about energy sensor? Does it work correctly?

EDIT: I found stupid mistake in script with energy sensor.

#16

New version: 0.1.1

Changelog:

  • fix energy sensor for Shelly Plug
#17

Where to send that command?
Via SSH from the Hassio mashine?
Or in the command line for mosquitto?

The energy sensor is added, but I am getting the following error message in the log.
State unknown for the sensor aswell

Exception in message_received when handling msg on ‘shellies/shellyplug-7BD83C/relay/0/energy’: ‘580’
Traceback (most recent call last):
File “/usr/local/lib/python3.7/site-packages/homeassistant/components/mqtt/sensor.py”, line 170, in message_received
payload, self._state)
File “/usr/local/lib/python3.7/site-packages/homeassistant/helpers/template.py”, line 174, in async_render_with_possible_json_value
return self._compiled.render(variables).strip()
File “/usr/local/lib/python3.7/site-packages/jinja2/asyncsupport.py”, line 76, in render
return original_render(self, *args, **kwargs)
File “/usr/local/lib/python3.7/site-packages/jinja2/environment.py”, line 1008, in render
return self.environment.handle_exception(exc_info, True)
File “/usr/local/lib/python3.7/site-packages/jinja2/environment.py”, line 780, in handle_exception
reraise(exc_type, exc_value, tb)
File “/usr/local/lib/python3.7/site-packages/jinja2/_compat.py”, line 37, in reraise
raise value.with_traceback(tb)
File “”, line 1, in top-level template code
TypeError: unsupported operand type(s) for /: ‘str’ and ‘int’

#18

You have to use mosquitto_pub command in container or machine where Mosquitto is installed via SSH. You can also send this via Services tab in HA.

image

Your traceback suggest that payload for energy topic is string. Can You confirm?

1 Like
#19

Thanks!

Confirmed via NodeRed, currently a 3 length string
image

#20

New version: 0.2.0

Changelog:

  • once again, fix energy sensor for Shelly Plug
  • add support for Shelly H&T