From ce875e564f55fbe8b49f03733ce52229b4c593c2 Mon Sep 17 00:00:00 2001
From: Vilppu Vuorinen <vilppu.vuorinen@jubic.fi>
Date: Tue, 11 Feb 2020 13:01:28 +0200
Subject: [PATCH] Add documentation for MELCloud integration (#11930)

* Add documentation for MELCloud integration

* Remove quotes from HA release

* Make the text flow

Co-Authored-By: Teemu R. <tpr@iki.fi>

* Make the text flow 2

Co-Authored-By: Teemu R. <tpr@iki.fi>

* Make the text flow 3

Co-Authored-By: Teemu R. <tpr@iki.fi>

* Add link to MELCloud

* Switch that abbreviation

* Clarify and update configuration.yaml setup

* Clarify configuration.yaml setup, vol 2

* Clarify token refresh

* Try to clarify the power control

* Update melcloud.markdown

Co-authored-by: Teemu R. <tpr@iki.fi>
Co-authored-by: Franck Nijhof <frenck@frenck.nl>
---
 source/_integrations/melcloud.markdown | 66 ++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 source/_integrations/melcloud.markdown

diff --git a/source/_integrations/melcloud.markdown b/source/_integrations/melcloud.markdown
new file mode 100644
index 00000000000..f88eaea2f9f
--- /dev/null
+++ b/source/_integrations/melcloud.markdown
@@ -0,0 +1,66 @@
+---
+title: MELCloud
+description: MELCloud integration
+logo: home-assistant.png
+ha_category:
+  - Climate
+ha_release: 0.106
+ha_iot_class: Cloud Polling
+ha_config_flow: true
+ha_codeowners:
+  - '@vilppuvuorinen'
+---
+
+The `melcloud` integration integrates Mitsubishi Electric's [MELCloud](https://www.melcloud.com/) enabled devices into Home Assistant.
+
+## Device support
+
+- Air-to-Air heat pumps, e.g., AC units - **Supported**
+- Air-to-Water heat pumps - **Work in progress**
+- Energy recovery ventilators - **Not supported**
+- Other - **Not supported**
+
+## Configuration
+
+The integration should be configured through the user interface ("Configurations -> Integrations") using the MELCloud login details. While not optimal, **the provided password is not stored**.
+
+An expired token needs to be updated manually by adding the MELCloud integration again with the same email address.
+
+Configuration is also possible through `configuration.yaml`. The required authentication token can be found in `X-MitsContextKey` header when logged into the MELCloud. The language needs to be set to English and the "Remember me" option needs to be selected.
+
+```yaml
+melcloud:
+  username: xxxx@xxxxxxx
+  token: xxxxxxxxxxxxxxxxxxx
+```
+
+{% configuration %}
+username:
+  description: Email address used to login to MELCloud
+  required: true
+  type: string
+token:
+  description: X-MitsContextKey access token
+  required: true
+  type: string
+{% endconfiguration %}
+
+## Air-to-Air device
+
+An Air-to-Air heat pump provides `climate` and `sensor` platforms.
+
+### Climate
+
+The following parameters can be controlled for the `climate` platform entities:
+
+- Power (using HVAC mode)
+- Target temperature
+- Operation mode (HVAC mode)
+- Fan speed
+
+### Sensor
+
+The following attributes are available for `sensor` platform entities:
+
+- Room temperature
+- Energy - The total consumed energy in kWh.