{"id":16609948,"url":"https://github.com/bieniu/ha-shellies-discovery","last_synced_at":"2025-04-05T12:09:06.127Z","repository":{"id":37568881,"uuid":"194319685","full_name":"bieniu/ha-shellies-discovery","owner":"bieniu","description":"Script that adds MQTT discovery support for Shellies devices","archived":false,"fork":false,"pushed_at":"2024-04-12T04:46:40.000Z","size":2435,"stargazers_count":280,"open_issues_count":0,"forks_count":89,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-04-12T12:18:24.366Z","etag":null,"topics":["discovery","hacktoberfest","home-assistant","mqtt","python","python-script","shelly"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bieniu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"custom":["https://www.paypal.me/bieniu79","https://www.buymeacoffee.com/QnLdxeaqO"]}},"created_at":"2019-06-28T18:46:44.000Z","updated_at":"2024-04-15T15:52:25.534Z","dependencies_parsed_at":"2023-02-12T22:46:09.806Z","dependency_job_id":"c5ec178a-38dc-4683-a65c-464cfa431da2","html_url":"https://github.com/bieniu/ha-shellies-discovery","commit_stats":null,"previous_names":[],"tags_count":210,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bieniu%2Fha-shellies-discovery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bieniu%2Fha-shellies-discovery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bieniu%2Fha-shellies-discovery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bieniu%2Fha-shellies-discovery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bieniu","download_url":"https://codeload.github.com/bieniu/ha-shellies-discovery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247332612,"owners_count":20921853,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discovery","hacktoberfest","home-assistant","mqtt","python","python-script","shelly"],"created_at":"2024-10-12T01:29:22.496Z","updated_at":"2025-04-05T12:09:06.101Z","avatar_url":"https://github.com/bieniu.png","language":"Python","funding_links":["https://www.paypal.me/bieniu79","https://www.buymeacoffee.com/QnLdxeaqO"],"categories":["Python"],"sub_categories":[],"readme":"# Shellies Discovery\n\n[![GitHub Release][releases-shield]][releases]\n[![GitHub All Releases][downloads-total-shield]][releases]\n[![hacs_badge][hacs-shield]][hacs]\n[![Community Forum][forum-shield]][forum]\n[![Buy me a coffee][buy-me-a-coffee-shield]][buy-me-a-coffee]\n[![PayPal_Me][paypal-me-shield]][paypal-me]\n[![Revolut.Me][revolut-me-shield]][revolut-me]\n\n![Screenshot](https://github.com/bieniu/ha-shellies-discovery/blob/master/images/shellies-integration.png?raw=true)\n\nThis script adds MQTT discovery support for Shelly devices in the [Home Assistant](https://home-assistant.io/).\n\n## Gen2/3 devices information\n\nPro/Plus devies are supported by [Shellies Discovery Gen2 script](https://github.com/bieniu/ha-shellies-discovery-gen2).\n\n## Prerequisites\n\nThis script needs Home Assistant `python_script` component so, if you never used it, I strongly suggest you to follow the [official instruction](https://www.home-assistant.io/integrations/python_script#writing-your-first-script) and check that `python_script` is properly configured and it's working.\n\nMQTT integration must be configured in Home Assistant.\n\n## Installation\n\nYou can download `shellies_discovery.py` file and save it in `\u003cconfig\u003e/python_scripts` folder or install the script via [HACS](https://hacs.xyz/).\nYou 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.\n\nAfter installing the script and adding automations, run `Shellies Announce` automation or restart Home Assistant twice.\n\nGo to [HA community](https://community.home-assistant.io/t/shellies-discovery-script/94048) for support and help.\n\n## Supported devices\n\n- Shelly 1 (with external sensors and external switch)\n- Shelly 1L (with external sensors)\n- Shelly 1PM (with external sensors)\n- Shelly 2 (relays and roller mode)\n- Shelly 2.5 (relays and roller mode)\n- Shelly 3EM\n- Shelly 4Pro\n- Shelly Air\n- Shelly Button1 (battery or USB powered)\n- Shelly Dimmer\n- Shelly Dimmer 2\n- Shelly Door/Window\n- Shelly Door/Window 2\n- Shelly DUO\n- Shelly DUO RGBW\n- Shelly EM\n- Shelly Flood\n- Shelly Gas (with Valve Add-on)\n- Shelly H\u0026T (battery or USB powered)\n- Shelly i3\n- Shelly Motion (battery or USB powered)\n- Shelly Motion 2 (battery or USB powered)\n- Shelly Plug\n- Shelly Plug S\n- Shelly Plug US\n- Shelly RGBW2 (color and white mode)\n- Shelly Sense (battery or USB powered)\n- Shelly Smoke\n- Shelly UNI (with external sensors)\n- Shelly Valve\n- Shelly Vintage\n\n## How to debug\n\nTo debug the script add this to your `logger` configuration:\n\n```yaml\n# configuration.yaml file\nlogger:\n  default: warning\n  logs:\n    homeassistant.components.python_script: debug\n    homeassistant.components.automation: info\n```\n\n## Troubleshooting checklist\n\n- correct MQTT configuration in Home Assistant with `discovery` enabled\n- same `discovery_prefix` in Home Assistant configuration and in script configuration\n- Shellies firmware updated to current version\n- Home Assistant updated to current version\n- enabled MQTT in Shellies configuration\n- you can't manually run the `shellies_discovery.py` script (`'dict object' has no attribute 'payload_json'` error)\n\n## Shelly device name\n\nThe script supports Shelly devices with non-standard names (`Internet \u0026 Security` -\u003e `Advanced - developer settings` -\u003e `Custom MQTT prefix` in the Shelly WWW panel).\nIf you want to change the name of the Shelly device, you must first remove the device from Home Assistant (`Configuration` -\u003e `Integrations` -\u003e `MQTT` -\u003e Device -\u003e `Remove`). Otherwise, all device entities will be duplicated.\n\n## Minimal configuration\n\n```yaml\n# configuration.yaml file\npython_script:\n\n# automations.yaml file\n- id: shellies_announce\n  alias: 'Shellies Announce'\n  triggers:\n    - trigger: homeassistant\n      event: start\n    - trigger: time_pattern\n      hours: \"/1\"  # Modifying this if you are using Shelly Motion can drain your device's battery quickly.\n  actions:\n    - action: mqtt.publish\n      data:\n        topic: shellies/command\n        payload: announce\n\n- id: 'shellies_discovery'\n  alias: 'Shellies Discovery'\n  mode: queued\n  max: 999\n  triggers:\n    - trigger: mqtt\n      topic: shellies/announce\n  conditions:\n    - condition: template\n      value_template: \"{{ trigger.payload_json.gen is not defined }}\"\n  actions:\n    - action: python_script.shellies_discovery\n      data:\n        id: '{{ trigger.payload_json.id }}'\n        mac: '{{ trigger.payload_json.mac }}'\n        fw_ver: '{{ trigger.payload_json.fw_ver }}'\n        model: '{{ trigger.payload_json.model | default }}'\n        mode: '{{ trigger.payload_json.mode | default }}'\n        host: '{{ trigger.payload_json.ip }}'\n```\n\n## Custom configuration example\n\n```yaml\n# configuration.yaml file\npython_script:\n\n# automations.yaml file\n- id: shellies_announce\n  alias: 'Shellies Announce'\n  triggers:\n    - trigger: homeassistant\n      event: start\n    - trigger: time_pattern\n      hours: \"/1\"  # Modifying this if you are using Shelly Motion can drain your device's battery quickly.\n  actions:\n    - actions: mqtt.publish\n      data:\n        topic: shellies/command\n        payload: announce\n\n- id: 'shellies_discovery'\n  alias: 'Shellies Discovery'\n  mode: queued\n  max: 999\n  triggers:\n    - trigger: mqtt\n      topic: shellies/announce\n  conditions:\n    - condition: template\n      value_template: \"{{ trigger.payload_json.gen is not defined }}\"\n  actions:\n    - action: python_script.shellies_discovery\n      data:\n        id: '{{ trigger.payload_json.id }}'\n        mac: '{{ trigger.payload_json.mac }}'\n        fw_ver: '{{ trigger.payload_json.fw_ver }}'\n        model: '{{ trigger.payload_json.model | default }}'\n        mode: '{{ trigger.payload_json.mode | default }}'\n        host: '{{ trigger.payload_json.ip }}'\n        discovery_prefix: 'hass'\n        qos: 2\n        shellytrv-84FD75:\n          default_heating_temperature: 21\n        shelly1-AABB9900:\n          relay-0: \"light\"\n          ext-temperature-0: true\n          ext-temperature-1: true\n          ext-temperature-2: true\n          force_update_sensors: true\n          ext-switch: true\n        shelly1pm-aabb9911:\n          ext-temperature-0: true\n          ext-humidity-0: true\n          push_off_delay: false\n          force_update_sensors: true\n        shelly1l-ddbb9911:\n          ext-temperature-0: true\n          ext-temperature-1: true\n          ext-temperature-2: true\n          ext-humidity-0: true\n        shellyswitch-123409FF:\n          relay-0: \"fan\"\n          relay-0-name: \"Bathroom Fan\"\n          relay-1: \"light\"\n          relay-1-name: \"Livingroom Light\"\n        shellyswitch-123409cc:\n          relay-1: \"fan\"\n        shellydimmer-883409cc:\n          light-0-name: \"Bedroom Lamp\"\n        shellyswitch25-334455AA:\n          roller-0-name: \"Garage\"\n          roller-0-class: \"garage\"\n        shellyplug-s-CCBBCCAA:\n          relay-0: \"light\"\n          force_update_sensors: true\n        shellyht-11AA00CCDD:\n          force_update_sensors: true\n          expire_after: 500\n        shellyht-11AA00CCEE:\n          powered: \"battery\"\n        shellyht-11AA00CCFF:\n          powered: \"ac\"\n        shellyswitch2-AA4455AA:\n          position_template: \"{{ '{% if value | float \u003c 30 %}0{% else %}{{ value }}{% endif %}' }}\"\n          set_position_template: \"{{ '{%if position | float \u003c 30 %}0{% else %}{{ position }}{% endif %}' }}\"\n        shellybutton1-112200CCFF:\n          powered: \"ac\"\n        shellymotionsensor-113300CCFF:\n          powered: \"ac\"\n        shellyrgbw2-AA123FF32:\n          light-1-name: \"Living room\"\n          light-2-name: \"Bedroom\"\n          light-3-name: \"Kitchen\"\n        shellyem-BB23CC45:\n          force_update_sensors: true\n        shellygas-AABBCC332211:\n          valve_connected: true\n        ignored_devices:\n          - shelly1-DD0011\n          - shellyem-EECC22\n```\n\n## Battery powered devices\n\nFor battery powered devices, the script requires you to set the value of 12h for `sleep_mode.period` or to configure `expire_after` yourself.\n\nDon't send `announce` topic more than once an hour if you're using Shelly Motion! This can quickly drain your device's battery.\n\n## How to use device automation triggers?\n\n![device_automation](https://github.com/bieniu/ha-shellies-discovery/blob/master/images/device-triggers.gif)\n\n\n## Script arguments\n\nkey | optional | type | default | description\n-- | -- | -- | -- | --\n`discovery_prefix` | True | string | `homeassistant` | MQTT discovery prefix\n`qos` | True | integer | `0` | MQTT QoS, you can use `0`, `1` or `2`\n`ignored_devices` | True | list | `None` | list of devices to ignore\n`ignore_device_model` | True | boolean | `false` | ignore device model to generate device name\n`optimistic` | True | boolean | `false` | `optimistic` | `optimistic` option for cover entities\n\n## Device arguments\n\nkey | optional | type | default | possible values | description\n-- | -- | -- | -- | -- | --\n`device_name` | True | string | | | name of the device\n`relay-\u003cNUM\u003e` | True | string | `switch` | `switch`, `light`, `fan` | component to use with the relay number `NUM`\n`relay-\u003cNUM\u003e-name` | True | string | None | string | friendly name of the relay number `NUM`\n`roller-\u003cNUM\u003e-name` | True | string | None | string | friendly name of the roller number `NUM`\n`roller-\u003cNUM\u003e-class` | True | string | None | string | [device_class](https://www.home-assistant.io/integrations/cover/#device-class) of the roller number `NUM`\n`light-\u003cNUM\u003e-name` | True | string | None | string | friendly name of the light number `NUM`\n`ext-temperature-\u003cNUM\u003e` | True | boolean | `false` | `true`, `false` | presence of temperature sensor number `NUM`\n`ext-humidity-\u003cNUM\u003e` | True | boolean | `false` | `true`, `false` | presence of humidity sensor number `NUM`\n`ext-switch` | True | boolean | `false` | `true`, `false` | presence of external switch\n`force_update_sensors` | True | boolean | `false` | `true`, `false` | [force update](https://www.home-assistant.io/integrations/sensor.mqtt/#force_update) for sensors\n`powered` | True | string | `battery` | `ac`, `battery` | `ac` or `battery` powered for Shelly H\u0026T, Motion, Sense and Button1\n`expire_after` | True | integer | `51840` | | [expire after](https://www.home-assistant.io/integrations/binary_sensor.mqtt/#expire_after) for battery powered sensors in seconds\n`use_fahrenheit` | True | boolean | `false` | `true`, `false` | whether the temperature sensor is configured in Fahrenheit for H\u0026T, Flood, Motion2 or DW2\n`default_heating_temperature` | True | float | `20` | | default target temperature after changing from OFF to HEAT mode\n`minimal_valve_position` | True | int | `0` | | this value should be equal to the MINIMAL VALVE POSITION LIMIT from Shelly Valve configuration\n`valve_connected` | True | boolean | `false` | `true`, `false` | is the Valve Add-on connected to Shelly Gas\n`humidity_topic` | True | string | | | Topic with humidity value ​​to display in the Shelly Valve climate entity\n\n\n[releases]: https://github.com/bieniu/ha-shellies-discovery/releases\n[releases-shield]: https://img.shields.io/github/release/bieniu/ha-shellies-discovery.svg?style=popout\n[downloads-total-shield]: https://img.shields.io/github/downloads/bieniu/ha-shellies-discovery/total\n[forum]: https://community.home-assistant.io/t/shellies-discovery-script/94048\n[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg?style=popout\n[buy-me-a-coffee-shield]: https://img.shields.io/static/v1.svg?label=%20\u0026message=Buy%20me%20a%20coffee\u0026color=6f4e37\u0026logo=buy%20me%20a%20coffee\u0026logoColor=white\n[buy-me-a-coffee]: https://www.buymeacoffee.com/QnLdxeaqO\n[paypal-me-shield]: https://img.shields.io/static/v1.svg?label=%20\u0026message=PayPal.Me\u0026logo=paypal\n[paypal-me]: https://www.paypal.me/bieniu79\n[hacs-shield]: https://img.shields.io/badge/HACS-Default-orange.svg\n[hacs]: https://hacs.xyz/docs/default_repositories\n[revolut-me-shield]: https://img.shields.io/static/v1.svg?label=%20\u0026message=Revolut\u0026logo=revolut\n[revolut-me]: https://revolut.me/maciejbieniek\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbieniu%2Fha-shellies-discovery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbieniu%2Fha-shellies-discovery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbieniu%2Fha-shellies-discovery/lists"}