diff --git a/README.md b/README.md index 7db4200fe7..d88bfe0f61 100644 --- a/README.md +++ b/README.md @@ -39,15 +39,6 @@ cached devices/entities from your HomeAssistant installation. This is necessary the device/entity naming system and is unable to remove previous entities installed by old versions of the component. Sorry about that. -## Towards Homeassistant official integration -My personal goal is to make this component fully compliant with Homeassistant, so -that it may be added as the official library to handle Meross devices. -However, before pushing a PullRequest to the official Homeassistant repository, I would like to share with to some users. -In this way we can test it massively, check it for any bug and make it **robust enough** to be seamlessly integrated -with Homeassistant. - -For now, the component has been integrated as a custom component into [HACS](https://custom-components.github.io/hacs/). - ## Installation & configuration You can install this component in two ways: via HACS or manually. HACS is a nice community-maintained components manager, which allows you to install git-hub hosted components in a few clicks. @@ -55,11 +46,13 @@ If you have already HACS installed on your HomeAssistant, it's better to go with On the other hand, if you don't have HACS installed or if you don't plan to install it, then you can use manual installation. ### Option A: Installing via HACS -If you have HACS, well, it's a piece of cake! Just search for "Meross" (Full name is Meross Cloud IoT) in the default repository of HACS and it'll show up! -Click on Install: when done, proceed with component setup. +If you have HACS, well, it's piece of cake! +Just search for "Meross" (Full name is Meross Cloud IoT) in the default repository of HACS and it'll show up. +Click on Install. When the installation completes, **you must restart homeassistant** in order to make it work. +As soon as HomeAssistant is restarted, you can proceed with __component setup__. ### Option B: Classic installation (custom_component) -1. Download the latest zip release archive from [here](https://github.com/albertogeniola/meross-homeassistant/releases/latest) (or clone the git master branch) +1. Download the latest zip release archive from [here](https://github.com/albertogeniola/meross-homeassistant/releases/latest) 1. Unzip/copy the meross_cloud directory within the `custom_components` directory of your homeassistant installation. The `custom_components` directory resides within your homeassistant configuration directory. Usually, the configuration directory is within your home (`~/.homeassistant/`). @@ -79,13 +72,46 @@ After a correct installation, your configuration directory should look like the **Note**: if the custom_components directory does not exist, you need to create it. +After copy-pasting the meross_cloud directory into the custom_components folder, you need to restart HomeAssistant. +As soon as HomeAssistant is restarted, you can proceed with __component setup__. + ### Component setup Once the component has been installed, you need to configure it in order to make it work. -To do so, simply add a new "integration" and look for Meross among the proposed ones. -The following animation shows how to do that. - +To do so, navigate to "Configuration -> Integrations -> Add Integration" and look for "Meross Cloud IoT". +As soon as you add it, you'll be asked to configure it. +The following table summarizes the fields that the wizard will require you to fill in: + +| Field Name | Example Value | Description | +|----------------------------------|-------------------------|---------------------------------------------------------| +| HTTP Api Endpoint | https://iot.meross.com | Is the HTTP(s) API endpoint used by the Meross Manager. This might vary in accordance with your country | +| Email Address | johndoe@gmail.com | Your Meross account username/email. If connecting to the official Meross cloud, use the same from the Meross App | +| Password | R4nd0mS3cret | Your Meross account password. If connecting to the official Meross cloud, use the same from the Meross App | +| Skip MQTT certificate validation | True (Checked) | Configures MQTT certificate validation. When unchecked it requires a valid certificate to be exposed from the Meross Server. If checked, it skips the MQTT certificate validation. If connecting to the official Meross cloud, you can uncheck this. When connecting to local-lan or custom MQTT brokers, you might want to check this. | + +The following animation shows an example of component configuration [![Installation via web UI](https://raw.githubusercontent.com/albertogeniola/meross-homeassistant/master/docs/source/images/components/meross_cloud/install-via-webui.gif)](https://raw.githubusercontent.com/albertogeniola/meross-homeassistant/master/docs/source/images/components/meross_cloud/install-via-webui.gif) +### API rate limiting + +Starting from version 1.1.0, this component has introduced the possibility to configure MQTT messaging rate limits. +You can configure such feature via component options configuration. + +The current version of this component implements a classic [Token Bucket](https://it.wikipedia.org/wiki/Token_bucket) +algorithm. More specifically, every device is subjected to its own token-bucket algorithm, driven by +`Single device MQTT burst limit` and `Single device MQTT rate limit` parameters. +On top of that, there is a global MQTT rate limiter (still implemented via Token Bucket), driven by +`Global MQTT burst limit` and `Global MQTT rate limit` parameters. + +| Field Name | Example Value | Description | +|----------------------------------|-----------------|---------------------------------------------------------| +| Enable MQTT Rate limits | True (Checked) | When checked, enables MQTT rate limiting. If unchecked, rate limiting is disabled. | +| Global MQTT burst limit | 10 | Maximum number of global MQTT messages that can be sent in a short time burst | +| Global MQTT rate limit | 4 | Global MQTT messages/second rate to allow | +| Single device MQTT burst limit | 3 | MQTT burst limit for a single device | +| Single device MQTT rate limit | 2 | MQTT rate limit for a single device | +| Single device max command queue length | 5 | Maximum commands that can be queued (delayed) for a single device. MQTT commands exceeding the queue length will be dropped by the limiter | + + ## Features ### Massive support This library supports all the Meross devices currently exposed by the Meross IoT library. diff --git a/custom_components/meross_cloud/manifest.json b/custom_components/meross_cloud/manifest.json index 7e21be9962..eb363d0b24 100644 --- a/custom_components/meross_cloud/manifest.json +++ b/custom_components/meross_cloud/manifest.json @@ -9,6 +9,6 @@ "config_flow": true, "quality_scale": "platinum", "iot_class": "cloud_push", - "version": "1.1.3", + "version": "1.1.4", "zeroconf": ["_meross-api._tcp.local."] } diff --git a/custom_components/meross_cloud/translations/en.json b/custom_components/meross_cloud/translations/en.json index 918995883d..6f7e333b2c 100644 --- a/custom_components/meross_cloud/translations/en.json +++ b/custom_components/meross_cloud/translations/en.json @@ -38,10 +38,10 @@ "init": { "data": { "enable_rate_limits": "Enable API rate limits", - "global_rate_limit_max_tokens": "Global API burst limit", - "global_rate_limit_per_second": "Global API rate limit (maximum api calls/second)", - "device_rate_limit_max_tokens": "Single device API burst limit", - "device_rate_limit_per_second": "Single device API rate limit (maximum api calls/second)", + "global_rate_limit_max_tokens": "Global MQTT burst limit", + "global_rate_limit_per_second": "Global MQTT rate limit (maximum api calls/second)", + "device_rate_limit_max_tokens": "Single device MQTT burst limit", + "device_rate_limit_per_second": "Single device MQTT rate limit (maximum api calls/second)", "device_max_command_queue": "Single device Maximum command queue length" }, "title": "Configure Manager" diff --git a/custom_components/meross_cloud/translations/it.json b/custom_components/meross_cloud/translations/it.json index 1f852f6186..69f800d01a 100644 --- a/custom_components/meross_cloud/translations/it.json +++ b/custom_components/meross_cloud/translations/it.json @@ -37,12 +37,12 @@ "step": { "init": { "data": { - "enable_rate_limits": "Abilita il limitatore delle chiamate API", + "enable_rate_limits": "Abilita il limitatore dei comandi MQTT", "global_rate_limit_max_tokens": "Limite burst rate globale", - "global_rate_limit_per_second": "Limite di chiamate al secondo globale", + "global_rate_limit_per_second": "Limite di comandi al secondo globale", "device_rate_limit_max_tokens": "Limite burst rate per singolo dispositivo", - "device_rate_limit_per_second": "Limite di chiamate al secondo per singolo dispositivo", - "device_max_command_queue": "Massimo numero di chiamate in coda per singolo dispositivo" + "device_rate_limit_per_second": "Limite di comandi al secondo per singolo dispositivo", + "device_max_command_queue": "Massimo numero di comandi in coda per singolo dispositivo" }, "title": "Configure Manager" } diff --git a/docs/source/_components/meross_cloud.markdown b/docs/source/_components/meross_cloud.markdown deleted file mode 100644 index fef531e212..0000000000 --- a/docs/source/_components/meross_cloud.markdown +++ /dev/null @@ -1,53 +0,0 @@ ---- -layout: page -title: "Meross devices platform" -description: "Instructions on how to integrate Meross devices into Home Assistant." -date: 2019-06-16 09:00 -sidebar: true -comments: false -sharing: true -footer: true -logo: meross.png -ha_category: - - Switch - - Light - - Cover -ha_iot_class: Cloud Push -ha_release: "0.94.3" ---- - -The `meross` platform allows you to control the state of your [Meross devices](https://www.meross.com/). - -The list of tested and fully supported devices is the following: -- MSL120 -- MSS110 -- MSS210 -- MSS310 -- MSS310h -- MSS425e -- MSS530h -- MSG100 - -Please note that the integration might be working also with unlisted Meross devices. -If you own any Meross plug, give it a try even if it's not listed. - - -In order to enable this integration, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -meross_cloud: - username: meross_username - password: meross_password -``` - -{% configuration %} -username: - description: The username of your Meross account. It's the email you use to login into the Meross app - required: true - type: string -password: - description: The password of your Meross account. It's the one you use to login into the Meross app. - required: true - type: string -{% endconfiguration %}