Shellies Discovery

This script adds MQTT discovery support for Shelly devices in the Home Assistant.

Gen2/3 devices information

Pro/Plus devies are supported by Shellies Discovery Gen2 script.

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.

MQTT integration must be configured in Home Assistant.

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.

After installing the script and adding automations, run Shellies Announce automation or restart Home Assistant twice.

Go to HA community for support and help.

Supported devices

Shelly 1 (with external sensors and external switch)
Shelly 1L (with external sensors)
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 Button1 (battery or USB powered)
Shelly Dimmer
Shelly Dimmer 2
Shelly Door/Window
Shelly Door/Window 2
Shelly DUO
Shelly EM
Shelly Flood
Shelly Gas (with Valve Add-on)
Shelly H&T (battery or USB powered)
Shelly i3
Shelly Motion (battery or USB powered)
Shelly Motion 2 (battery or USB powered)
Shelly Plug
Shelly Plug S
Shelly Plug US
Shelly RGBW2 (color and white mode)
Shelly Sense (battery or USB powered)
Shelly Smoke
Shelly UNI (with external sensors)
Shelly Valve
Shelly Vintage

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 ('dict object' has no attribute 'payload_json' 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

# 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
  condition:
    - condition: template
      value_template: "{{ trigger.payload_json.gen is not defined }}"
  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 | default }}'
      mode: '{{ trigger.payload_json.mode | default }}'
      host: '{{ trigger.payload_json.ip }}'

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
  condition:
    - condition: template
      value_template: "{{ trigger.payload_json.gen is not defined }}"
  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 | default }}'
      mode: '{{ trigger.payload_json.mode | default }}'
      host: '{{ trigger.payload_json.ip }}'
      discovery_prefix: 'hass'
      qos: 2
      shellytrv-84FD75:
        default_heating_temperature: 21
      shelly1-AABB9900:
        relay-0: "light"
        ext-temperature-0: true
        ext-temperature-1: true
        ext-temperature-2: true
        force_update_sensors: true
        ext-switch: true
      shelly1pm-aabb9911:
        ext-temperature-0: true
        ext-humidity-0: true
        push_off_delay: false
        force_update_sensors: true
      shelly1l-ddbb9911:
        ext-temperature-0: true
        ext-temperature-1: true
        ext-temperature-2: true
        ext-humidity-0: true
      shellyswitch-123409FF:
        relay-0: "fan"
        relay-0-name: "Bathroom Fan"
        relay-1: "light"
        relay-1-name: "Livingroom Light"
      shellyswitch-123409cc:
        relay-1: "fan"
      shellydimmer-883409cc:
        light-0-name: "Bedroom Lamp"
      shellyswitch25-334455AA:
        roller-0-name: "Garage"
        roller-0-class: "garage"
      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"
      shellyswitch2-AA4455AA:
        position_template: "{{ '{% if value | float < 30 %}0{% else %}{{ value }}{% endif %}' }}"
        set_position_template: "{{ '{%if position | float < 30 %}0{% else %}{{ position }}{% endif %}' }}"
      shellybutton1-112200CCFF:
        powered: "ac"
      shellymotionsensor-113300CCFF:
        powered: "ac"
      shellyrgbw2-AA123FF32:
        light-1-name: "Living room"
        light-2-name: "Bedroom"
        light-3-name: "Kitchen"
      shellyem-BB23CC45:
        force_update_sensors: true
      shellygas-AABBCC332211:
        valve_connected: 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?

Script arguments

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
`ignore_device_model`	True	boolean	`false`	ignore device model to generate device name
`optimistic`	True	boolean	`false`	`optimistic`

Device arguments

key	optional	type	default	possible values	description
`device_name`	True	string			name of the device
`relay-<NUM>`	True	string	`switch`	`switch`, `light`, `fan`	component to use with the relay number `NUM`
`relay-<NUM>-name`	True	string	None	string	friendly name of the relay number `NUM`
`roller-<NUM>-name`	True	string	None	string	friendly name of the roller number `NUM`
`roller-<NUM>-class`	True	string	None	string	device_class of the roller number `NUM`
`light-<NUM>-name`	True	string	None	string	friendly name of the light 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`
`ext-switch`	True	boolean	`false`	`true`, `false`	presence of external switch
`force_update_sensors`	True	boolean	`false`	`true`, `false`	force update for sensors
`powered`	True	string	`battery`	`ac`, `battery`	`ac` or `battery` powered for Shelly H&T, Motion, Sense and Button1
`expire_after`	True	integer	`51840`		expire after for battery powered sensors in seconds
`use_fahrenheit`	True	boolean	`false`	`true`, `false`	whether the temperature sensor is configured in Fahrenheit for H&T, Flood, Motion2 or DW2
`default_heating_temperature`	True	float	`20`		default target temperature after changing from OFF to HEAT mode
`minimal_valve_position`	True	int	`0`		this value should be equal to the MINIMAL VALVE POSITION LIMIT from Shelly Valve configuration
`valve_connected`	True	boolean	`false`	`true`, `false`	is the Valve Add-on connected to Shelly Gas

Name		Name	Last commit message	Last commit date
Latest commit History 896 Commits
.github		.github
images		images
python_scripts		python_scripts
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
README.md		README.md
hacs.json		hacs.json
info.md		info.md
requirements-dev.txt		requirements-dev.txt
requirements-test.txt		requirements-test.txt
ruff.toml		ruff.toml

License

bieniu/ha-shellies-discovery

Folders and files

Latest commit

History

Repository files navigation

Shellies Discovery

Gen2/3 devices information

Prerequisites

Installation

Supported devices

How to debug

Troubleshooting checklist

Shelly device name

Minimal configuration

Custom configuration example

Battery powered devices

How to use device automation triggers?

Script arguments

Device arguments

About

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project

Languages