honeywell - Fix issue 18932 & clean up the mess (#9587)

* clean up docs

* less notes

* ad first warning back in

* ✏️ Tweak

* ✏️ Tweak

source/_components/honeywell.markdown

@@ -16,54 +16,67 @@ redirect_from:
  - /components/climate.honeywell/
 ---
 
+The `honeywell` climate platform lets you control Honeywell TCC (Total Connect Comfort) climate systems from Home Assistant. It does not integrate with Honeywell TCC alarm systems.
 
-The `honeywell` climate platform let you control Honeywell Connected thermostats from Home Assistant.
+<p class='note'>
+There is some potential confusion over this integration because it is currently implemented as a combination of two _distinct_ climate systems, one being US-based, the other is EU-based.
 
-To set it up, add the following information to your `configuration.yaml` file:
+These two regions are _not_ interchangeable, so you must be clear which applies to your climate system.
+</p>
+
+## {% linkable_title US-based Systems %}
+
+These systems are based in North America, and temperatures are usually in Fahrenheit. They would likely be HVAC systems. They always use the [somecomfort](https://github.com/kk7ds/somecomfort) client library. In this integration, this is called the `us` region.
+
+If your system is US-based, then you can access your system via [https://mytotalconnectcomfort.com/portal/](https://mytotalconnectcomfort.com/portal/) (note the `/portal/`).
+
+## {% linkable_title EU-based Systems %}
+
+These systems are based in Europe (including the UK & Ireland), and temperatures are usually in Celsius. They would likely be heating-only systems. They always use the [evohome-client](https://github.com/watchforstock/evohome-client) client library. In this integration, this is called the `eu` region.
+
+If your system is US-based, then you can access it via [https://international.mytotalconnectcomfort.com/](https://international.mytotalconnectcomfort.com/) (note the `international`).
+
+The `eu` region is soon to be deprecated, and ongoing support for such systems is available via the [evohome](/components/evohome/) integration.
+
+## {% linkable_title Configuration %}
+
+To set up this integration, first confirm your region, then add the following information to your **configuration.yaml** file (the below example is for US-based systems):
 
 ```yaml
 climate:
   - platform: honeywell
     username: YOUR_USERNAME
     password: YOUR_PASSWORD
-    scan_interval: 600
+    region: us
 ```
-<p class='note'>
-Scan interval is expressed in seconds. Omitting or mis-configuring `scan_interval` may result in too-frequent polling and cause you to be rate-limited by Honeywell.
-</p>
 
 {% configuration %}
 username:
-  description: The username of an user with access.
+  description: Email address of an account with access the TCC website for your region.
   required: true
   type: string
 password:
-  description: The password for your given admin account.
+  description: Password for the account.
   required: true
   type: string
 region:
-  description: Region identifier (either 'eu' or 'us').  Use the `somecomfort` client library for `us`, and evohome-client for `eu`.
+  description: Region identifier, either 'eu' or 'us'.
   required: false
   default: eu
   type: string
-scan_interval:
-  description: Scan interval is expressed in seconds. Recommended value of 600 seconds. Omitting scan_interval may result in too-frequent polling and cause you to rate-limited by Honeywell.
-  required: false
-  default: 120
-  type: integer
 away_temperature:
-  description: "(*only for eu region*) Heating setpoint when away mode is on, in deg C."
+  description: "(*only for the EU region*) Heating setpoint when away mode is on, in degrees Celsius."
   required: false
   default: 16.0
   type: float
 away_cool_temperature:
-  description: "(*only for us region*) Cooling setpoint when away mode is on, in deg C."
+  description: "(*only for the US region*) Cooling setpoint when away mode is on, in degrees Fahrenheit."
   required: false
-  default: 30.0
+  default: 88
-  type: float
+  type: integer
 away_heat_temperature:
-  description: "(*only for us region*) Heating setpoint when away mode is on, in deg C."
+  description: "(*only for the US region*) Heating setpoint when away mode is on, in degrees Fahrenheit."
   required: false
-  default: 16.0
+  default: 61
-  type: float
+  type: integer
 {% endconfiguration %}