Documentation fixes and additions.

Author: jmattsson

docs/source/data.rst

@@ -2,35 +2,54 @@ Data Available in ``homeassistant-powersensor``
 ================================================
 The data provided in the home assistant integration should be reflective of exactly the data available
 in the devices screen of the powersensor app with the exception of the top level view provided by the virtual
-household
+household.
 
 Virtual Household
 ------------------
 Built on top of the sensors, the API provided by `powersensor_local <https://github.com/DiUS/python-powersensor_local>`_
-provides a ``virtual household``. This view is captures the key data most users want to capture at the household level
+provides a ``virtual household``. This view is captures the key data most users want to capture at the household level.
 This includes
 
 * Energy imported from the grid
 * Total home energy usage
 * Energy exported to the grid (from solar)
 * Total solar production
 
-As well as the corresponding instantaneous power consumption/production.
+as well as the corresponding instantaneous power consumption/production.
+
+.. note::
+
+  Powersensor deals with *net* readings, meaning that the energy import and
+  export direction is determined by the sign of value. Home Assistant however
+  requires *gross* readings, where values are always positive and divided
+  into separate import and export values instead.
+
+  The Virtual Household view performs the necessary calculations to match
+  Home Assistant's needs in order to easily use Powersensor data in its
+  Energy dashboard. However, you will find that the Total Energy shown for
+  the sensor(s) generally do not match what's shown under the household
+  view. This is expected and is a consequence of going from net to gross.
+  The energy readings will reset to zero whenever Home Assistant is restarted,
+  but HomeAssistant tracks the overall total correctly.
+
+The household readings update as sensor data becomes available.
 
 Plugs
 -----
 Each plug exposes 6 entities reflecting the different measurements made by the plug these are
 
-* Active Current
-* Apparent Current
 * Power
-* Reactive Current
 * Total Energy Consumption
+* Active Current
+* Reactive Current
+* Apparent Current
 * Voltage
 
-This is the full extend of data available via the plug api, but much of this data is redundant and future
-releases intend to make these optional selections when the integration is configured
+Of these only the power and total energy are commonly of interest, and future
+releases intend to make the others optional inclusions when the integration
+is configured.
 
+The plug readings typically update every second.
 
 Sensors
 -------
@@ -41,4 +60,14 @@ Each sensor exposes
 * Power
 * Total Energy
 
-Any of these entities can be used in automation workflows
+The sensor readings typically update every 30 seconds, but are dependent on the
+sensor being within range of a plug to act as a relay for it. If sensors aren't
+showing up as expected, use the mobile app to check which plug it's trying
+to relay though, and the signal strength. If necessary, relocate a plug to
+somewhere closer to the sensor to improve the signal strength.
+
+Automations
+-----------
+
+Any of the plug, sensor or virtual household  entities can be used in
+automation workflows.

docs/source/index.rst

@@ -5,7 +5,7 @@ integration for `Powersensor <https://www.powersensor.com.au/>`_ devices,
 and is primarily a wrapper around the `powersensor_local <https://dius.github.io/python-powersensor_local/>`_ API
 allowing access to for data from Powersensor devices in Home Assistant.
 
-This integration enables users to view their local powersensor data within home assistant as well as exposing
+This integration enables users to view their local powersensor data within Home Assistant as well as exposing
 various sensors that can be used for home automation and interfaces with other smart devices.
 
 .. toctree::

docs/source/installation.rst

@@ -12,21 +12,23 @@ Before installing this integration, ensure you have:
 * Home Assistant 2024.1.0 or newer
 * Access to your Home Assistant configuration directory
 * `powersensor_local <https://github.com/DiUS/python-powersensor_local>`_ 2.0.0 or later installed in your Home Assistant instance's python environment
-* Firmware updated to version 8107 or later on powersensor hardware (plugs and sensors)
+* Firmware updated to version 8129 or later on powersensor hardware (plugs and sensors)
 
 From Source
 ------------
-Clone or download this repo e.g
+Clone or download this repo e.g.
+
 .. code-block:: bash
 
    git clone https://github.com/DiUS/homeassistant-powersensor.git
 
 Copy or symlink the directory ``custom_components/powersensor`` to your Home Assistant configuration directory.
 When launching homeassistant, e.g.
+
 .. code-block:: bash
 
    hass --config ./config
 
 Home assistant should automatically discover powersensor devices on the same network.
 Follow the links for Settings/Devices&Services. At the top you should be prompted add ``powersensor`` to your
-homeassistant instance.
+homeassistant instance.