Next step (#4)

* Add name to the sensor description * Add support for custom MQTT prefix * Update documentation
bieniu · Jan 25, 2022 · dd658f6 · dd658f6
1 parent 4e858dd
commit dd658f6
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 10 deletions.
diff --git a/LICENSE b/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2022 Maciej Bieniek
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/README.md b/README.md
@@ -1,4 +1,21 @@
-# ha-shellies-discovery-gen2
+# Shellies Discovery Gen2
+
+[![GitHub Release][releases-shield]][releases]
+[![GitHub All Releases][downloads-total-shield]][releases]
+[![Buy me a coffee][buy-me-a-coffee-shield]][buy-me-a-coffee]
+[![PayPal_Me][paypal-me-shield]][paypal-me]
+
+This script adds MQTT discovery support for Shelly Gen2 devices in the [Home Assistant](https://home-assistant.io/).
+
+## Prerequisites
+
+This 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.
+
+For the device to work with the script, it must have MQTT configured and options `RPC status notifications over MQTT` and `Generic status update over MQTT` enabled.
+
+## Installation
+
+You can download `shellies_discovery_gen2.py` file and save it in `<config>/python_scripts` folder.
 
 ## Supported devices
 
@@ -10,9 +27,43 @@
 - Shelly Pro 2PM
 - Shelly Pro 4PM
 
-## Required automations
+## How to debug
+
+To debug the script add this to your `logger` configuration:
+
+```yaml
+# configuration.yaml file
+logger:
+  default: warning
+  logs:
+    homeassistant.components.python_script: debug
+    homeassistant.components.automation: info
+```
+
+## Supported platforms
+
+- switch
+- light
+- sensor
+
+## Supported features
+
+- the device name is taken from the device configuration
+- the relay name is taken from the device configuration
+- the relay consumption type is taken from the device configuration
+- custom MQTT prefixes are supported
+
+## Known problems
+
+- availability doesn’t work (firmware change is needed)
+
+## Minimal configuration
 
 ```yaml
+# configuration.yaml file
+python_script:
+
+# automations.yaml file
 - id: shellies_announce_gen2
   alias: "Shellies Announce Gen2"
   trigger:
@@ -23,11 +74,11 @@
   action:
     - service: mqtt.publish
       data:
-        topic: "shellypro4pm-aabbcc/rpc"
+        topic: "shellypro4pm-aabbcc/rpc"  # shellypro4pm-aabbccddeeff is a device ID
         payload: "{{ device_info_payload }}"
     - service: mqtt.publish
       data:
-        topic: "shellyplus1pm-112233/rpc"
+        topic: "shellyplus1pm-112233/rpc"  # shellyplus1pm-112233445566 is a device ID
         payload: "{{ device_info_payload }}"
 
 - id: shellies_discovery_gen2
@@ -43,3 +94,11 @@
       id: "{{ trigger.payload_json.src }}"
       device_config: "{{ trigger.payload_json.result }}"
 ```
+
+[releases]: https://github.com/bieniu/ha-shellies-discovery-gen2/releases
+[releases-shield]: https://img.shields.io/github/release/bieniu/ha-shellies-discovery-gen2.svg?style=popout
+[downloads-total-shield]: https://img.shields.io/github/downloads/bieniu/ha-shellies-discovery-gen2/total
+[buy-me-a-coffee-shield]: https://img.shields.io/static/v1.svg?label=%20&message=Buy%20me%20a%20coffee&color=6f4e37&logo=buy%20me%20a%20coffee&logoColor=white
+[buy-me-a-coffee]: https://www.buymeacoffee.com/QnLdxeaqO
+[paypal-me-shield]: https://img.shields.io/static/v1.svg?label=%20&message=PayPal.Me&logo=paypal
+[paypal-me]: https://www.paypal.me/bieniu79
diff --git a/python_scripts/shellies_discovery_gen2.py b/python_scripts/shellies_discovery_gen2.py
@@ -86,6 +86,7 @@
 DESCRIPTION_SENSOR_CURRENT = {
     KEY_DEVICE_CLASS: DEVICE_CLASS_CURRENT,
     KEY_ENABLED_BY_DEFAULT: False,
+    KEY_NAME: "Current",
     KEY_STATE_CLASS: STATE_CLASS_MEASUREMENT,
     KEY_STATE_TOPIC: TOPIC_SWITCH_RELAY,
     KEY_UNIT: UNIT_AMPERE,
@@ -94,6 +95,7 @@
 DESCRIPTION_SENSOR_ENERGY = {
     KEY_DEVICE_CLASS: DEVICE_CLASS_ENERGY,
     KEY_ENABLED_BY_DEFAULT: True,
+    KEY_NAME: "Energy",
     KEY_STATE_CLASS: STATE_CLASS_TOTAL_INCREASING,
     KEY_STATE_TOPIC: TOPIC_SWITCH_RELAY,
     KEY_UNIT: UNIT_WATTH,
@@ -102,6 +104,7 @@
 DESCRIPTION_SENSOR_POWER = {
     KEY_DEVICE_CLASS: DEVICE_CLASS_POWER,
     KEY_ENABLED_BY_DEFAULT: True,
+    KEY_NAME: "Power",
     KEY_STATE_CLASS: STATE_CLASS_MEASUREMENT,
     KEY_STATE_TOPIC: TOPIC_SWITCH_RELAY,
     KEY_UNIT: UNIT_WATT,
@@ -110,6 +113,7 @@
 DESCRIPTION_SENSOR_POWER_FACTOR = {
     KEY_DEVICE_CLASS: DEVICE_CLASS_POWER_FACTOR,
     KEY_ENABLED_BY_DEFAULT: False,
+    KEY_NAME: "Power Factor",
     KEY_STATE_CLASS: STATE_CLASS_MEASUREMENT,
     KEY_STATE_TOPIC: TOPIC_SWITCH_RELAY,
     KEY_UNIT: UNIT_PERCENT,
@@ -118,6 +122,7 @@
 DESCRIPTION_SENSOR_TEMPERATURE = {
     KEY_DEVICE_CLASS: DEVICE_CLASS_TEMPERATURE,
     KEY_ENABLED_BY_DEFAULT: False,
+    KEY_NAME: "Temperature",
     KEY_STATE_CLASS: STATE_CLASS_MEASUREMENT,
     KEY_STATE_TOPIC: TOPIC_SWITCH_RELAY,
     KEY_UNIT: UNIT_CELSIUS,
@@ -126,6 +131,7 @@
 DESCRIPTION_SENSOR_VOLTAGE = {
     KEY_DEVICE_CLASS: DEVICE_CLASS_VOLTAGE,
     KEY_ENABLED_BY_DEFAULT: False,
+    KEY_NAME: "Voltage",
     KEY_STATE_CLASS: STATE_CLASS_MEASUREMENT,
     KEY_STATE_TOPIC: TOPIC_SWITCH_RELAY,
     KEY_UNIT: UNIT_VOLT,
@@ -246,7 +252,7 @@ def get_switch(relay, relay_type):
         KEY_UNIQUE_ID: f"{device_id}-{relay}".lower(),
         KEY_QOS: qos,
         KEY_DEVICE: device_info,
-        "~": f"{device_id}/",
+        "~": default_topic,
     }
     return topic, payload
 
@@ -276,7 +282,7 @@ def get_light(relay, relay_type):
         KEY_UNIQUE_ID: f"{device_id}-{relay}".lower(),
         KEY_QOS: qos,
         KEY_DEVICE: device_info,
-        "~": f"{device_id}/",
+        "~": default_topic,
     }
     return topic, payload
 
@@ -291,11 +297,11 @@ def get_sensor(sensor, description, relay=None):
             f"{disc_prefix}/sensor/{device_id}-{relay}-{sensor}/config"
         )
         unique_id = f"{device_id}-{relay}-{sensor}".lower()
-        sensor_name = f"{switch_name} {sensor.replace('_', ' ').title()}"
+        sensor_name = f"{switch_name} {description[KEY_NAME]}"
     else:
         topic = encode_config_topic(f"{disc_prefix}/sensor/{device_id}-{sensor}/config")
         unique_id = f"{device_id}-{sensor}".lower()
-        sensor_name = f"{device_name} {sensor.replace('_', ' ').title()}"
+        sensor_name = f"{device_name} {description[KEY_NAME]}"
 
     payload = {
         KEY_NAME: sensor_name,
@@ -309,7 +315,7 @@ def get_sensor(sensor, description, relay=None):
         KEY_UNIQUE_ID: unique_id,
         KEY_QOS: qos,
         KEY_DEVICE: device_info,
-        "~": f"{device_id}/",
+        "~": default_topic,
     }
 
     if description.get(KEY_DEVICE_CLASS):
@@ -350,6 +356,7 @@ def configure_device(relays, relay_sensors):
 firmware_id = device_config["sys"]["device"][ATTR_FW_ID]
 mac = device_config["sys"]["device"][ATTR_MAC]
 device_name = device_config["sys"]["device"][ATTR_NAME]
+default_topic = f"{device_config['mqtt']['topic_prefix']}/"
 
 model = device_id.rsplit("-", 1)[0]