Add doumentation using just-the-docs

docs/_config.yml

@@ -0,0 +1,17 @@
+title: Heatmiser Neo Home Assistant
+remote_theme: just-the-docs/just-the-docs
+
+search_enabled: true
+search:
+  heading_level: 3
+
+# Back to top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+gh_edit_link: true # show or hide edit this page link
+gh_edit_link_text: "Edit this page on GitHub"
+gh_edit_repository: "https://https://github.com/MindrustUK/Heatmiser-for-home-assistant" # the github URL for your repo
+gh_edit_branch: "dev" # the branch that your docs is served from
+gh_edit_source: docs # the source that your files originate from
+gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately

docs/experimental.md

@@ -0,0 +1,9 @@
+---
+title: Experimental
+nav_order: 8
+---
+
+There are various features that have been developed but due to lack of devices to test with are less likely to work fully. Please raise an issue including the diagnostics data and describe the issue you are seeing.
+
+- NeoAir
+- NeoStatHC

docs/faqs.md

@@ -0,0 +1,80 @@
+---
+title: FAQs
+nav_order: 9
+---
+
+# Troubleshooting
+
+## I can't find my Neohub
+
+### Try discovery using nmap
+
+As suggested by Haakon Storm Heen, try namp on your local network range:
+
+`nmap -Pn -p4242 -oG - 192.168.1.0/24 | grep 4242 | grep -i open`
+
+Where supported by your network and machine you can use a tool such as ZeroConfServiceBrowser or "Discovery - DNS-SD
+Browser" (iPhone) to detect the mDNS broadcast from the hub. Look for "\_hap.\_tcp." and the "Heatmiser neoHub" should be
+listed as a device.
+
+Note: If you discover the device via mdns/zeroconf then you can use the hostname advertised by the service.
+
+### Using Heatmiser Discovery
+
+Note: This will eventually be part of the setup process and done internally.
+
+- Start a listener in a terminal: `nc -ulk -p 19790`
+- Issue the discovery command `echo -n "hubseek" | nc -b -u 255.255.255.255 19790`
+
+A response such as `hubseek{"ip":"192.168.0.2","device_id":"nn:nn:nn:nn:nn:nn"}` should then be rendered in the
+listening terminal.
+
+## I can't connect to my Neohub
+
+- If you are not using token based authentication;
+
+  - Check the Heatmiser Mobile App and under _SETTINGS_ -> _API_ -> _API TOKENS_ ensure that _Legacy API_ is enabled.
+
+  - After checking the above please try testing with the hub using the following commands from the Home Assistant
+    terminal (Provided by the addon "Terminal & SSH");
+  - `printf '{"INFO":0}\0' | nc YOUR_DEVICE_IP_HERE 4242`
+
+- If you are trying to authenticate using token based authentication;
+  - The following instructions are a placeholder for now and will be further expanded on once the integration better
+  - supports token based authentication via web sockets.
+  - Ensure you are applying this configuration to a Heatmiser NeoHub 2 or later. The Version 1 Hub does not support this
+    authentication mechanism.
+  - Ensure that your token is correct, this can be checked in the Heatmiser mobile app under _SETTINGS_ -> _API_ ->
+    _API TOKENS_
+  - Use postman to troubleshoot.
+
+### The info command times out
+
+- Have you tried to ping the neohub? `ping IP_ADDRESSS_HERE` if this fails the Neohub is likely unreachable for some
+  reason.
+
+## Other common troubleshooting steps to try
+
+- Try restarting Home Assistant.
+- Check the logs: Within Home Assistant, from the _Settings_ menu navigate to _Logs_ and look for anything relating to
+  _Heatmiser_.
+- Enable debugging and check the logs again:
+  - Within Home Assistant, from the _Settings_ menu navigate to _Devices & Services_ and then to
+    _Heatmiser Neo Climate_ and from the left side menu select _Enable debug logging_.
+  - Now navigate to _Developer Tools_ and then to _RESTART_, when prompted select _Restart Home Assistant_ follow the
+    steps above to check the logs again.
+- Remove the existing installation and re-install: To ensure total removal of the _Heatmiser Neo Climate_ integration
+  using Home Assistant terminal (Provided by the addon "Terminal & SSH") issue the following command;
+  `rm -rf /config/custom_components/heatmiserneo` restart Home Assistant and install from fresh.
+
+## Bug Reporting and asking for help:
+
+- Please ensure that if you wish to report a bug that is not fixed in the [Dev Branch](https://github.com/MindrustUK/Heatmiser-for-home-assistant/tree/dev) before submitting your bug.
+- Include diagnostics output, logs, versions, any troubleshooting attempted, outputs and expected vs observed behaviour.
+- Please note "It doesn't work" and other vague "It's broken" messages will only prompt a lot of questions to understand
+  why things are broken, the more information upfront will help expedite any advice and resolution.
+
+## Diagnostics
+
+- You can download diagnostics from any of the device information pages
+  ![Diagnostics](/images/faq_1.png)

docs/hub.md

@@ -0,0 +1,24 @@
+---
+title: Hub
+nav_order: 6
+---
+
+The NeoHub device contains system wide entities and configuration parameters
+
+# Controls
+
+- DST Rule: Select the rule that enables and disables DST automatically. Alternatively set DST on or off permanently. Only UK, EU and NZ rules are supported by heatmiser
+- NTP - enable or disable NTP (Network Time Protocol). When enabled, thermostat clocks should be synched automatically
+- Time Zone - The base timezone for the system
+
+## Helper Sensors/Entities
+
+- Away - whether the hub is set to permanently away
+- Holiday - whether the hub is on holiday/temporarily away
+- Holiday End - the end date of a holiday
+
+## Diagnostic Entities
+
+- Identify - A button to flash an led on the hub
+- DST - whether DST is currently active or not
+- ZigBee Channel - reports the ZigBee channel being used for communication between the hub and devices

docs/index.md

@@ -0,0 +1,10 @@
+---
+title: Home
+nav_order: 1
+---
+
+# Heatmiser-for-home-assistant
+
+An integration for [Home Assistant](https://www.home-assistant.io/) to add support for [Heatmiser's Neo-Hub and 'Neo'](https://www.heatmiser.com/en/heatmiser-neo-overview/) range of products.
+
+This is a work in progress for adding Heatmiser Neo-hub support to [Home Assistant](https://home-assistant.io/), I maintain this as a weekend project only so don't expect fast updates but feel free to raise issues as needed.

docs/installation.md

@@ -0,0 +1,75 @@
+---
+title: Installation
+nav_order: 2
+---
+
+# Installation:
+
+Before starting installation you should know the IP address of the Neo-hub. If you don't know the IP address, use one of the approaches suggested below to find your neo-hubs IP address.
+
+It is suggested that you should allocate a static IP to the Heatmiser Neo-hub or use a DNS entry that's resolvable by Home-Assistant (see notes below).
+
+The preferred method of installation is using HACS although the legacy, cut-and-paste method of installation can still be used and is described under Options below. Installing via HACS is a two-stage process. Firstly, add the Heatmiser repository to HACS, then secondly adding the Heatmiser Integration to Home Assistant.
+
+HACS is available from [here](https://github.com/hacs) and there are copious resources available (e.g. [HACS XYZ](http://hacs.xyz)) about its installation. This will involve lots of Home Assistant restarts! Once you have HACS running...
+
+## Stage 1: Add to HACS
+
+Open HACS and go to the Settings tab
+
+![CustomIntegration](/images/installation_1.png)
+
+Add "https://github.com/MindrustUK/Heatmiser-for-home-assistant" as a repository as an "Integration" type, note you need to include the quote marks around the repository name.
+Go to the Integrations tab
+Search for "Heatmiser Neo Integration", (it will probably be at the bottom!) select and install
+
+![CustomRepositories](/images/installation_2.png)
+
+When this message appears follow it by going to Configuration -> Server Tools and then "Restart"
+![RestartNotice](/images/installation_3.png)
+
+## Stage 2: Configure the integration in HA:
+
+Go to Configuration -> Integrations and click on the orange icon in the bottom right corner produces a drop down list and scroll down to "Heatmiser Neo Climate".
+
+![HowToIntegrate](/images/installation_4.png)
+
+When the integration starts you may need to enter the Neo-hub IP address. The port is always 4242.
+
+![Config](/images/installation_5.png)
+
+If you are successful, after restarting HA you will see the results under Configuration -> Entities
+
+![Entities](/images/installation_6.png)
+
+# (Optional) Pre-relase Installation:
+
+You can use the `Redownload` functionality in HACS to chose a prerelease version if you want to try the latest development features.
+
+# (Optional) Legacy Installation:
+
+## For Hass.io:
+
+Install and configure SSH server from the "Add-on store". Once you have shell run the following:
+
+```
+mkdir -p /config/custom_components
+cd /tmp/
+git clone https://github.com/MindrustUK/Heatmiser-for-home-assistant /tmp/heatmiserneo
+mv /tmp/heatmiserneo/custom_components/heatmiserneo /config/custom_components/
+rm -rf /tmp/heatmiserneo/
+```
+
+Restart Home Assistant and setup the integration.
+
+## For Windows 10 Manual installation:
+
+Install and configure Samba Share from the "Add-on store". Change directory to config location then run the following:
+
+```
+Create a network drive pointing at your Home Assistant config directory.
+If there is not a sub-directory in this drive called custom_components create it.
+Now create a subdirectory under custom_components called heatmiserneo.
+Download all the files from the Heatmiser-for-home-assistant Github repository.
+Copy and paste all those files into the new Home Assistant heatmiserneo sub-directory.
+```

docs/services.md

@@ -0,0 +1,94 @@
+---
+title: Services
+nav_order: 7
+---
+
+# Thermostat Services
+
+## Hold
+
+You can apply a hold using the `heatmiserneo.hold_on` service. This can be used to target an entity, device or area and also accepts the following parameters:
+
+- `hold_duration` - how long to hold the specified temperature. This is given in Home Assistant duration format (hh:mm e.g. `hold_duration: 01:30`) and can go up to 99:59.
+- `hold_temperature` - sets the temperature to hold. Specified as an integer (e.g. `hold_temperature: 20`).
+
+If there is an existing hold on any device targeted by the service call, it is replaced by the new hold.
+
+```yaml
+action: heatmiserneo.hold_on
+data:
+  hold_duration:
+    hours: 0
+    minutes: 45
+    seconds: 0
+  hold_temperature: 21.5
+target:
+  entity_id: climate.kitchen
+```
+
+## Release Hold
+
+You can release any existing hold on a NeoStat specified by entity, device or area. There are no other parameters.
+
+```yaml
+action: heatmiserneo.hold_off
+data: {}
+target:
+  entity_id: climate.kitchen
+```
+
+# Timeclock Services (NeoStats in TimeClock mode or NeoPlugs)
+
+## Hold
+
+Setting a custom timer hold can be done using the `heatmiserneo.timer_hold_on` service.
+
+- `hold_duration` - how long to hold the specified temperature. This is given in Home Assistant duration format (hh:mm e.g. `hold_duration: 01:30`) and can go up to 99:59.
+- `hold_state` - a boolean that specifies if the output should be held on or off (eg if a profile currently has the output on, it is possible to turn it off).
+
+```yaml
+action: heatmiserneo.timer_hold_on
+data:
+  hold_duration:
+    hours: 0
+    minutes: 45
+    seconds: 0
+  hold_state: true
+target:
+  entity_id: select.hot_water
+```
+
+Note that an override can also be set by calling the built in `select.select_option` service, but a default duration of 30 minutes is used instead:
+
+```yaml
+action: select.select_option
+data:
+  option: override_off
+target:
+  entity_id: select.hot_water
+```
+
+Use `override_off` or `override_on` to set the hold off or on.
+
+The TimeClock will automatically go back to `Auto` once the duration has passed. But one can also use the `select.select_option` service to end it early by setting the option to `auto` (or `standaby`). Note that NeoPlugs have additional options of `manual_on` and `manual_off`.
+
+# Hub Services
+
+## Away
+
+You can control the away/holiday state of the hub (and all attached devices) using the `heatmiserneo.set_away_mode` service. There are three general use cases:
+
+- Turn off away/holiday mode
+- Turn on away mode (with no end date)
+- Turn on holiday mode (away with and end date)
+
+You should target the NeoHub device itself or the Away entity of the hub. The `end` parameter is optional. It should not be supplied if `away` is `false`, and it can optionally be supplied when `away` is `true`
+
+```
+action: heatmiserneo.set_away_mode
+data:
+  away: true
+  end: "2025-01-01 15:00:00"
+target:
+  entity_id: binary_sensor.neohub_192_168_1_10_away
+```

docs/stat.md

@@ -0,0 +1,54 @@
+---
+title: Thermostats
+nav_order: 3
+---
+
+# Thermostat usage guide
+
+The thermostats work like any other Home Assistant climate entity.
+
+## Preset Modes
+
+There are three preset modes:
+
+- Home - The thermostat will follow a profile
+- Boost - The thermostat is set to 2 degrees higher for 30 minutes
+- Away - The thermostat is in frost protection mode. The thermostat is not following a profile and will only call for heat if the temperature drops below the configured frost protection temperature.
+  > ##### WARNING
+  >
+  > NOTE: Setting any thermostat to Away will change all thermostats and timers to Away. Turning off a single thermostat can be done by changing the mode to off
+  > {: .block-warning }
+
+## Helper Sensors/Entities
+
+- Hold Time Remaining - If a hold/override is active, displays the number of minutes left
+- Hold Temperature - Shows the hold temperature (only relevant if hold is active)
+- Current Temperature - optional sensor that holds the current temperature (can also be obtained as an attribute of the climate entity)
+- Floor Temperature - displays the floor temperature if a floor sensor is connected (can also be obtained as an attribute of the climate entity)
+- Active Profile - Can select a different profile for the thermostat.
+  - PROFILE_0 is a special profile when the profile is managed directly on the thermostat rather than a shared profile managed in the hub
+- Profile Next Time - The next time there is a state change managed by the profile
+- Profile Current Temeperature - The profile's current temperature
+- Profile Next Temeperature - The profile's temperature at the next state change
+
+  > ##### INFO
+  >
+  > NOTE: Profile entities are only relevant if the hub is not in non-programmable mode
+
+## Configuration Entities
+
+- Frost Temperature - The frost protection temperature when the device is on standby/away/holiday
+- Output Delay - delay before the thermostat can call for heat again after switching off
+- Optimum Start - maxiumu preheat period
+- Switching Differential - How far the temperature has to drop before heat is called for
+- Floor Limit Temperature - Thermostat will stop calling for heat if the floor reaches this temperature (only if a floor sensor is in use)
+
+## Diagnostic Entities
+
+- Hold Active - shows if a hold is in place
+- Standby - if the device is in standby
+- Away - if the hub is away (eg indefinitely away)
+- Holiday - if the hub is in holiday mode (eg away with an end date)
+- Device Temperature - NeoStats in TimeClock mode still have access to the temperature
+- Identify - A button to flash the screen of a NeoStat in TimeClock mode
+- Floor Limit Reached - shows if the output is off because the floor limit temperature has been reached