Merge pull request #54 from artmg/dev

Release v2023.3.19 from dev into master
ha-warmup · Mar 19, 2023 · 7ba1ba3 · 7ba1ba3
2 parents 4c10cc6 + f9da463
commit 7ba1ba3
Show file tree

Hide file tree

Showing 13 changed files with 222 additions and 74 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,7 +7,8 @@ so that you can decide whether to upgrade,
 which version might suit you the best, 
 and what issues you might face.
 
-The most recent versions come first, and the Release Dates are YYYY-MM-DD
+The most recent versions come first, and the Release Versions 
+are based on date using format YYYY.M.D (no leading zeroes)
 
 ## Unreleased
 
@@ -19,8 +20,6 @@ Recent features from development that have not been formally released yet:
 
 ### Changed
 
-* Converted README and LICENSE to Markdown
-* Clarified install instructions following user feedback #30 #31
 * 
 
 ### Fixed
@@ -36,6 +35,43 @@ Recent features from development that have not been formally released yet:
 * 
 
 
+## 2023.3.19
+
+This is a MAJOR release. Previously this project was focussed on 
+a manually installed cusom_component. This release re-organised it 
+to be primarily a HACS integration that still works if installed manually.
+
+See README for details of new usage, and how to obtain old release if you have issues
+
+### Added
+
+* f345c03 Include HACS metadata files, and recent additions to components manifest
+* 57bfef6 Add unique id to the WarmupThermostat entity.
+* d9e4755 Added support notes for 6ie model
+* b91983a additional notes on devices supported from issue #33
+
+### Changed
+
+* 0175088 Reorgansied documentation (especially README) to adjust for new focus on HACS install, with manual as alternative
+* b60d38a Update README instructions for backwards compatibility with manual installations
+* e272be1 Restructured folders ready for HACS compatibility – moved the `warmup` folder into a new `custom_components` folder
+* 5fc20de Clarified install instructions following user feedback #30 #31
+* f4a2ca9 Converted README and LICENSE to Markdown
+
+### Fixed
+
+* b8d34e7 bring `dev` branch up to date so it can start receiving PRs for testing
+* 6dedb42 removed `temperature utility` ready to use new `TemperatureConverter` where needed - fix for #42
+
+### Deprecated
+
+* none
+
+### Removed
+
+* Old documentation referring to HACS not being supported
+
+
 ## 2021.5.23
 
 Mainly intended to keep the component working once HA 2021.6 is released - thanks to @rct for his contributions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -27,3 +27,15 @@ Please raise an issue if you want further guidance on developing new features or
 
 Once you have completed your development and testing on your changes, 
 then please raise a Pull Request for us to be able to merge in your work. They should be merged into the **dev** branch.
+
+## Release
+
+Before bringing changes into the **master** branch, please ensure that you have referenced the changes into [CHANGELOG.md](CHANGELOG.md)
+
+When releasing a version, please ensure that you update the version in 
+
+custom_components/warmup/manifest.json
+
+Since 2021.5.23, the versioning format has been YYYY.M.D (no leading zeroes), and this should be applied to new Github Releases too.
+
+
diff --git a/README.md b/README.md
@@ -1,43 +1,25 @@
 # Introduction
 
-This software is a Custom Component to integrate Warmup devices into
-[Home Assistant](https://www.home-assistant.io/).
+This software is a Custom Component to integrate 
+Warmup under-floor heating devices into 
+[Home Assistant](https://www.home-assistant.io/). 
+It is compatible with the Home Assistant Community Store (HACS).
+
+[Warmup Plc](https://www.warmup.co.uk/) 
+manufacture under-floor heating (UFH) and control systems, 
+including a range of wifi-enabled home thermostats. 
+Some of these thermostats, such as the 
+[4IE](https://www.warmup.co.uk/thermostats/smart/4ie-underfloor-heating) 
+and 6IE, have an API. 
+This software enables communication via this API, 
+and allows Home Assistant to read and control the supported devices, 
+using a python script to perform the integration. 
+
+You may install this integration from the 
+Home Assistant Community Store (HACS), 
+or continue reading below for instructions 
+on the **manual installation** of this component.
 
-[Warmup](https://www.warmup.co.uk/) manufacture underfloor heating and
-control systems and their wifi-enabled home thermostat, [warmup
-4IE](https://www.warmup.co.uk/thermostats/smart/4ie-underfloor-heating),
-has an API. This software enables communication via this API, and allows
-Home Assistant to read and control the device (currently just this one
-model).
-
-For instructions on how to **install** this component please keep
-reading below.
-
-There is more detailed documentation on the API and the information
-returned from the device on the [documentation
-wiki](https://github.com/ha-warmup/warmup/wiki). If you have issues
-using this software then please check our [Issue
-list](https://github.com/ha-warmup/warmup/issues) and if someone else
-has not already, then do raise a new issue. If you wish you become more
-involved with the project then please see our [guide to
-contributing](https://github.com/ha-warmup/warmup/blob/master/CONTRIBUTING.md).
-
-## History
-
-This code is derived from some great work by
-[\@alex0103](https://github.com/alex-0103) to create a [Home Assistant
-Custom Component and Python
-Package](https://github.com/alex-0103/warmup4IE). This has been improved
-by a number of coders, notably
-[\@foxy82](https://github.com/foxy82/warmup4IE) and the code was
-origianlly inspired by [\@alyc100](https://github.com/alyc100)\'s
-project for SmartThingsHub
-[here](https://github.com/alyc100/SmartThingsPublic/blob/master/devicetypes/alyc100/warmup-4ie.src/warmup-4ie.groovy).
-Many Thanks to all the contributors who helped us get here.!
-
-Warmup Plc was not involved in the creation of this software and has not
-sanctioned or endorsed it in any way. 4IE is a registered trademark of
-Warmup Plc.
 
 ## License
 
@@ -48,19 +30,38 @@ This software is published under Apache 2.0 license. Please see LICENSE.md.
 The library is primary intended to interface the 4IE with home
 assistant, but may also be used standalone.
 
-## Home Assistant
+## Register with My Warmup
+
+Before you can use this component, 
+you need to register for a Warmup account. 
+See <https://my.warmup.com/login>
 
-This is a **Custom Component** for manual inclusion in a **Home Assistant Core** installation (manual using Python virtual environment). Note that it is **not** a _Custom repository_ for Home Assistant Operating System (HAOS) or Home Assistant Container deployments.
 
-### Register with My Warmup
+## Home Assistant Community Store
 
-To setup this component, you need to register to warmup first. see
-<https://my.warmup.com/login>
+In your HACS store, look in the _Integrations_ page. 
+In the top right corner select the 3-dots menu, 
+and choose _Custom repositories_. 
+Paste in the URL to this repo, 
 
-### Deploy custom component
+<https://github.com/ha-warmup/warmup/>
 
-Then copy the contents of the `warmup` subfolder into
-custom_components in your HA **config** folder, e.g.:
+and select _Category_: **Integration**. 
+
+For help see <https://hacs.xyz/docs/faq/custom_repositories/>
+
+
+## Manual installation
+
+Here are instructions for you to install this software as a 
+**Custom Component** that is manually included 
+in a **Home Assistant Core** installation 
+(manual using Python virtual environment). 
+
+### Install custom component
+
+You need to copy the contents of the `custom_components/warmup` subfolder 
+into in your HA **config** folder, e.g.:
 
 ```sh
 cd path/to/your/config
@@ -70,14 +71,21 @@ git clone https://github.com/ha-warmup/warmup.git /tmp/warmup
 # remove any previous version
 rm -r ./custom_components/warmup 2>/dev/null
 mkdir -p ./custom_components/warmup
-cp -r /tmp/warmup/warmup/* ./custom_components/warmup
+cp -r /tmp/warmup/custom_components/warmup/* ./custom_components/warmup
 # clean up
 rm -rf /tmp/warmup/
 ```
 
-NB: the component folder has been renamed from `warmup_cc` to simply `warmup`, in line with recommendations from the HA
-project.
+#### alternative versions
 
+If you are testing a specific branch, like `dev`, then you would `git clone -b dev https...etc` to get the branch you need. 
+
+In the unlikely event that you cannot manually install 
+the HACS compatible version of this custom component, 
+you may go back to the last release before HACS compatibility, 
+[Release v23.02](https://github.com/ha-warmup/warmup/releases/tag/v23.02). 
+Please refer to the README inside that source file for the 
+legacy commands to deploy the custom component manually.
 
 #### Warnings in logs
 
@@ -92,7 +100,7 @@ you should see the following warning in the logs:
 This is a positive sign, as it means 
 the custom component has been successfully loaded. Great! - now carry on.
 
-### Add the warmup platform manually via YAML
+#### Add the warmup platform manually via YAML
 
 Then add to your configuration.yaml:
 
@@ -112,23 +120,15 @@ climate:
 After restarting home assistant, the component will be loaded
 automatically.
 
-### Add your devices to the dashboard
-
-Our wiki has some [ideas on how to configure warmup
-devices](https://github.com/ha-warmup/warmup/wiki/Configuration-ideas)
-in your Home Assistant instance.
-
-
-
-## Standalone
+### Standalone
 
 You may install the library via pip using
 
 ```python
 >>> pip install warmup4ie
 ```
 
-After that, import the library, and away we go.
+After that, import the library, and away you go.
 
 ```python
 >>> import warmup4ie
@@ -138,6 +138,26 @@ After that, import the library, and away we go.
 >>> device.get_current_temperature()
 ```
 
+### Other installation types
+
+We do **not currently** have instructions for using this software as 
+a _Custom repository_ for **Home Assistant Operating System** (HAOS) 
+or **Home Assistant Container** deployments, 
+but you are welcome to use our issue tracker 
+to discuss any potential improvements to this project. 
+
+
+## Configuration
+
+### Add your devices to the dashboard
+
+Our wiki has some [ideas on how to configure warmup
+devices](https://github.com/ha-warmup/warmup/wiki/Configuration-ideas)
+in your Home Assistant instance.
+
+
+
+
 # Status
 
 ## Supported models
@@ -146,16 +166,61 @@ After that, import the library, and away we go.
     - this is the device for which this project was launched, so has reasonable support
 * 6IE
     - this newer device has shown teething issues here, but seems to work with some caveats
-    - your wifi network SSID length must be <= 32 characters and password <= 15 characters
+    - try keeping your wifi network SSID length <= 32 characters and password <= 15 characters
     - you cannot set it up as 'living room', but you can choose 'kitchen' and change through the warmup web interface 
     - please see [6ie Thermostat compatibility issues #33](https://github.com/ha-warmup/warmup/issues/33) for details
 
+Note that some models may not have `comma` on the keyboard, which may also limit your choice of wireless network SSID and Password.
+
 ## Supported Features
 
 At the moment the library supports reading current temperature, target
 temperature plus other values from the thermostat and setting the target
 temperature, switching between manual, automatic and frost protection
-mode, switching the device off. and setting a temporary override.
+mode, switching the device off, and setting a temporary override.
 
 For further information on versions please see the
 [CHANGELOG](https://github.com/ha-warmup/warmup/blob/master/CHANGELOG.md)
+
+## Find out more
+
+There is more detailed documentation on the API and the information
+returned from the device on the [documentation
+wiki](https://github.com/ha-warmup/warmup/wiki). If you have issues
+using this software then please check our [Issue
+list](https://github.com/ha-warmup/warmup/issues) and if someone else
+has not already, then do raise a new issue. If you wish you become more
+involved with the project then please see our [guide to
+contributing](https://github.com/ha-warmup/warmup/blob/master/CONTRIBUTING.md).
+
+### `ha-warmup` is an independent project
+
+Please note that Warmup Plc were not involved 
+in the creation of this software. 
+We do, however, acknowledge their ownership of 
+registered trademarks relating to their brand and products. 
+
+### History
+
+Many Thanks to all the contributors helped us get here!
+
+Originally inspired by 
+[\@alyc100](https://github.com/alyc100)\'s
+project for SmartThingsHub
+[here](https://github.com/alyc100/SmartThingsPublic/blob/master/devicetypes/alyc100/warmup-4ie.src/warmup-4ie.groovy), 
+this code is derived from some great work by
+[\@alex0103](https://github.com/alex-0103) to create a [Home Assistant
+Custom Component and Python
+Package](https://github.com/alex-0103/warmup4IE). 
+That has been improved by a number of coders, notably
+[\@foxy82](https://github.com/foxy82/warmup4IE), 
+with valuable contributions and support from 
+[\@artmg](https://github.com/artmg/warmup), 
+[\@rct](https://github.com/rct/warmup), 
+[\@robchandhok](https://github.com/robchandhok/warmup),
+[\@kkoenen](https://github.com/kkoenen/warmup).
+
+Thank you to the community who continue to 
+be involved with and support this project, 
+and encourage others to use it. 
+
diff --git a/warmup/__init__.py → custom_components/warmup/__init__.py b/warmup/__init__.py → custom_components/warmup/__init__.py
diff --git a/warmup/climate.py → custom_components/warmup/climate.py b/warmup/climate.py → custom_components/warmup/climate.py
diff --git a/custom_components/warmup/manifest.json b/custom_components/warmup/manifest.json
@@ -0,0 +1,12 @@
+{
+  "domain": "warmup",
+  "name": "Warmup",
+  "codeowners": ["@ha-warmup"],
+  "dependencies": [],
+  "documentation": "https://github.com/ha-warmup/warmup/",
+  "integration_type": "hub",
+  "iot_class": "cloud_polling",
+  "issue_tracker": "https://github.com/ha-warmup/warmup/issues/",
+  "requirements": [],
+  "version": "2023.03.15-beta"
+}
diff --git a/warmup/services.yaml → custom_components/warmup/services.yaml b/warmup/services.yaml → custom_components/warmup/services.yaml
diff --git a/warmup/warmup4ie/Main.py → custom_components/warmup/warmup4ie/Main.py b/warmup/warmup4ie/Main.py → custom_components/warmup/warmup4ie/Main.py
diff --git a/warmup/warmup4ie/__init__.py → ...m_components/warmup/warmup4ie/__init__.py b/warmup/warmup4ie/__init__.py → ...m_components/warmup/warmup4ie/__init__.py
diff --git a/warmup/warmup4ie/warmup4ie.py → ..._components/warmup/warmup4ie/warmup4ie.py b/warmup/warmup4ie/warmup4ie.py → ..._components/warmup/warmup4ie/warmup4ie.py
diff --git a/hacs.json b/hacs.json
@@ -0,0 +1,11 @@
+{
+  "name": "Warmup under-floor heating integration",
+  "render_readme": false,
+  "domains": [
+    "climate"
+  ],
+  "iot_class": [
+    "Cloud Polling"
+  ]
+
+}
diff --git a/info.md b/info.md
@@ -0,0 +1,22 @@
+This is a Custom Component to integrate Warmup 
+under-floor heating devices into Home Assistant. 
+
+Warmup Plc manufacture under-floor heating (UFH) 
+and control systems, 
+including a range of wifi-enabled home thermostats. 
+Some of these thermostats, such as the 4IE and 6IE, 
+have an API. 
+This software enables communication via this API, 
+and allows Home Assistant to read and control the supported devices, 
+using a python script to perform the integration. 
+It is compatible with the Home Assistant Community Store (HACS).
+
+Please note that Warmup Plc were not involved 
+in the creation of this software, 
+but we acknowledge their ownership of 
+registered trademarks relating to their brand and products. 
+
+For further information please see the full project README at 
+https://github.com/ha-warmup/warmup
+
+[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/ha-warmup/warmup)
diff --git a/warmup/manifest.json b/warmup/manifest.json