Merge branch 'mega' into feature/P028-add-error-state-value-option

docs/source/Plugin/P007.rst

@@ -24,7 +24,7 @@ Used libraries: |P007_usedlibraries|
 Introduction
 ------------
 
-The PCF8591 is an Analog to Digital converter, connected via an I2C bus. The plugin supports to read from 1 up to 4 input values. If desired, multiple Tasks *can* be defined, addressing other, or duplicate, inputs.
+The PCF8591 is an Analog to Digital and Digital to Analog converter, connected via an I2C bus. The plugin supports to read from 1 up to 4 input values, and has a single analog output that can be changed by a command. If desired, multiple Tasks *can* be defined, addressing other, or duplicate, inputs.
 
 Supported hardware
 ------------------
@@ -54,6 +54,8 @@ I2C Options
 
 The available settings here depend on the build used. At least the **Force Slow I2C speed** option is available, but selections for the I2C Multiplexer can also be shown. For details see the :ref:`Hardware_page`
 
+As the chip is specified to only work correctly up to 100 kHz, the **Force Slow I2C speed** checkbox should normally be *enabled*.
+
 * **I2C Address**: The address the device is using. There are a number of addresses the module can use, and they can usually be set at the board using jumper pins.
 
 The available options:
@@ -88,6 +90,34 @@ When selecting f.e. the Quad option and saving the settings, the number of outpu
 
    For any 'excess' values, events *will* be generated!
 
+Hardware configuration
+^^^^^^^^^^^^^^^^^^^^^^
+
+* **Input mode** The chip supports several input modes, the desired mode can be selected here.
+
+Available options are:
+
+.. image:: P007_InputModeOptions.png
+  :alt: Input mode options
+
+* *4 single-ended inputs* De standard configuration is to have 4 inputs that are measured with regards to GND.
+* *3 differential inputs, A0/A1/A2 differential with AIN3* AIN0 .. AIN2 are measured differential to AIN3, resulting in 3 available values.
+* *2 single-ended, A0, A1, AIN2/AIN3 differential -> A2* AIN0 and AIN1 are measured with regards to GND into the first 2 values, the third value is measured differentially from AIN2 and AIN3.
+* *AIN0/AIN1 differential -> A0, AIN2/AIN3 differential -> A1* 2 values are measured, the first differentially from AIN0 and AIN1, and the second differentially from AIN2 and AIN3.
+
+When configuring a differential option from above list, the 4th and 3rd values are undefined when not used, but can still be read. The results are then undefined.
+
+The chip documentation describes it like this:
+
+.. image:: P007_InputModeSchematics.png
+  :alt: Chip documentation for Input mode
+
+* **Enable Analog output (AOUT)** Enabling the Analog output has 2 effects:
+
+1) The AOUT pin can be set to a linear value in the range 0..255 between 0V and Vref (Vref can sometimes be set using a potentiometer on the board) using the ``analogout`` command (see below).
+
+2) The internal oscillator will be enabled continuesly, causing higher power usage, but also improved measurements when reading an analog input as it avoids the startup time of the oscillator that can cause inaccurate readings.
+
 Data Acquisition
 ^^^^^^^^^^^^^^^^
 
@@ -100,10 +130,10 @@ Values
 
 The name for the value(s) is initially set to a default name, but can be changed if desired. Also, a formula can be entered to re-calculate a value before display/sending to a controller, and the number of decimals can be changed, for a Temperature, usually 1 decimal is enough to be displayed (value will be rounded).
 
-.. Commands available
-.. ^^^^^^^^^^^^^^^^^^
+Commands available
+^^^^^^^^^^^^^^^^^^
 
-.. .. include:: P007_commands.repl
+.. include:: P007_commands.repl
 
 .. Events
 .. ~~~~~~
@@ -116,6 +146,9 @@ Change log
 .. versionchanged:: 2.0
   ...
 
+  |added|
+  2022-05-08 Selection of Input mode, Enable Analog output (AOUT) and ``analogout`` command.
+
   |added|
   2021-08-06 Selection of 1 to 4 input values to be read.
 

docs/source/Plugin/P007_commands.repl

@@ -0,0 +1,14 @@
+.. csv-table::
+        :header: "Command", "Extra information"
+        :widths: 20, 30
+
+        "
+        ``analogout,<value>``
+
+        Value: 0..255
+
+        ","
+        The value is linearly scaled from 0V to Vref. Vref is often the same as VCC for the chip, but can sometimes be configured using a potentiometer on the board.
+
+        Only available if **Enable Analog output (AOUT)** is enabled.
+        "

docs/source/Plugin/P093.rst

@@ -53,8 +53,6 @@ Parts required to make a CN105 female connector
 * `PAP-05V-S <https://www.digikey.com/product-detail/en/jst-sales-america-inc/PAP-05V-S/455-1489-ND/759977>`_,
 * `SPHD-002T-P0.5 <https://www.digikey.com/product-detail/en/jst-sales-america-inc/SPHD-002T-P0.5/455-1313-1-ND/608809>`_,
 
-One can also get `premade pigtails <http://www.usastore.revolectrix.com/Products_2/Cellpro-4s-Charge-Adapters_2/Cellpro-JST-PA-Battery-Pigtail-10-5-Position>`_.
-
 Example using D1 mini PRO
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -89,7 +87,23 @@ Commands
 Example
 -------
 
-A full working example using openHAB can be found `here <https://community.openhab.org/t/mitsubishi-heat-pump/91765>`_.
+There are several ways how to control AC unit using ESP Easy.
+
+**Using HTTP:**
+
+Generally commands are send via http using syntax ``http://<espeasyip>/control?cmd=<command>`` where ``<espeasyip>`` is the IP of your ESP Easy device, for example ``192.168.0.100``:
+
+.. include:: P093_examples_http.repl
+
+**Using MQTT:**
+
+Commands are send via MQTT using syntax ``<MQTT subscribe template>/cmd`` with payload: ``<command>``. For example, if your `unit name <https://espeasy.readthedocs.io/en/latest/Config/Config.html#unit-name>`_ is ``MyESPEasy``, one would send the below payload to topic ``MyESPEasy/cmd``:
+
+.. include:: P093_examples_mqtt.repl
+
+Please check `here <https://espeasy.readthedocs.io/en/latest/Reference/Command.html>`_ for more details on how to send commands using ESP Easy.
+
+Please `check <https://community.openhab.org/t/mitsubishi-heat-pump/91765>`_ for an example integration with openHAB.
 
 Special thanks
 --------------

docs/source/Plugin/P093_commands.repl

@@ -1,5 +1,5 @@
 .. csv-table::
-        :header: "Command", "Extra information"
+        :header: "Command", "Description"
         :widths: 20, 40
 
         "

docs/source/Plugin/P093_examples_http.repl

@@ -0,0 +1,19 @@
+.. csv-table::
+        :header: "Command", "Description"
+        :widths: 20, 40
+
+        "
+        ``http://192.168.0.100/control?cmd=MitsubishiHP,power,ON``
+        ","
+        Turn on AC
+        "
+        "
+        ``http://192.168.0.100/control?cmd=MitsubishiHP,temperature,23``
+        ","
+        Set target temperature to 23
+        "
+        "
+        ``http://192.168.0.100/control?cmd=MitsubishiHP,fan,AUTO``
+        ","
+        Set fan mode to ``AUTO``
+        "

docs/source/Plugin/P093_examples_mqtt.repl

@@ -0,0 +1,19 @@
+.. csv-table::
+        :header: "Payload", "Description"
+        :widths: 20, 40
+
+        "
+        ``MitsubishiHP,power,ON``
+        ","
+        Turn on AC
+        "
+        "
+        ``MitsubishiHP,temperature,23``
+        ","
+        Set target temperature to 23
+        "
+        "
+        ``MitsubishiHP,fan,AUTO``
+        ","
+        Set fan mode to ``AUTO``
+        "

docs/source/Plugin/P132.rst

@@ -0,0 +1,127 @@
+.. include:: ../Plugin/_plugin_substitutions_p13x.repl
+.. _P132_page:
+
+|P132_typename|
+==================================================
+
+|P132_shortinfo|
+
+Plugin details
+--------------
+
+Type: |P132_type|
+
+Name: |P132_name|
+
+Status: |P132_status|
+
+GitHub: |P132_github|_
+
+Maintainer: |P132_maintainer|
+
+Used libraries: |P132_usedlibraries|
+
+Description
+-----------
+
+The INA3221 Voltage/Current sensor can be used to measure voltage and/or current for DC input, up to 26V. It has 3 separate channels available.
+
+It can be used to replace the :ref:`p027_page`, except that the I2C protocol isn't directly compatible, so it is not a drop-in replacement.
+
+Configuration
+-------------
+
+.. image:: P132_DeviceConfiguration.png
+  :alt: Device Configuration
+
+**Name** A unique name should be entered here.
+
+**Enabled** The device can be disabled or enabled. When not enabled the device should not use any resources.
+
+I2C Options 
+^^^^^^^^^^^^
+
+The available settings here depend on the build used. At least the **Force Slow I2C speed** option is available, but selections for the I2C Multiplexer can also be shown. For details see the :ref:`Hardware_page`
+
+**I2C Address**: The address the sensor is using. The different addresses can be selected by connecting the appropriate signal to ``A0``. Often also documented on the board.
+
+.. image:: P132_I2CAddressOptions.png
+  :alt: Available I2C address options
+
+Device Settings
+^^^^^^^^^^^^^^^
+
+* **Power value 1..4**: As a plugin only has 4 available output values and the sensor has 6 values available, here we have to select what output receives what measured value.
+
+Available options are:
+
+.. image:: P132_PowerValueOptions.png
+  :alt: Available Power Value options
+
+* *Current channel 1..3*: Measure the current from channel 1..3.
+* *Voltage channel 1..3*: Measure the voltage from channel 1..3.
+
+NB: To get all measured values, an extra Task can be configured to provide the measurements not handled in the current task, or you could f.e. configure separate tasks for Voltage and Current measurements. These tasks shouldn't interfere, assuming both get the same configuration settings for **Shunt resistor**, **Averaging samples** and **Conversion rate Voltage** / **Conversion rate Current**.
+
+Hardware
+^^^^^^^^
+
+* **Shunt resistor**: As there are different hardware configurations available for the board, using different shunt resistor values, here you can select the value that is present on the board used.
+
+.. image:: P132_ShuntResistorOptions.png
+  :alt: Available options for shunt resistor values
+
+Measurement
+^^^^^^^^^^^
+
+* **Averaging samples**: To increase the accuracy of measurements, the chip allows to take the average value for a set of samples. The desired number of samples can be selected in this setting, default: 1.
+
+.. image:: P132_AveragingSamplesOptions.png
+  :alt: Averaging samples options
+
+When combining a higher number of samples with a longer **Conversion rate**, taking all possible measurements will require more time, affecting the **Interval** that would be feasible for a reliable measurement. The worst-case scenarios (maximum **Conversion rate** settings) have been calculated, and are shown as a note below this setting.
+
+* **Conversion rate Voltage/Current**: To change the accuracy of measurements, a different conversion rate can be selected. Lowering the conversion rate will decrease the accuracy, and allow a higher sampling frequency, but as the measurements are read at a smallest **Interval** of 1 second, there isn't much use in lowering the conversion rate. When increasing the conversion rate, accuracy will increase, but, also depending on the **Averaging samples** configured, increases the time it takes to complete all measurements. (Calculation formula below).
+
+There are separate **Conversion rate** settings for the **Voltage** and **Current** measurements, as that's available in the chip.
+
+.. image:: P132_ConversionRateOptions.png
+  :alt: Conversion rate options
+
+To calculate the minimally required **Interval** setting for the task, this formula can be used:
+
+  | (3 * Averaging samples * Conversion rate Voltage) + (3 * Averaging samples * Conversion rate Current), and round that up to a seconds value.
+
+  | Example: (Worst case) 3 * 1024 * 0.008244 + 3 * 1024 * 0.008244 = 50.65 seconds => ~51 minimum Interval.
+
+  | Example: (Default case) 3 * 1 * 0.00144 + 3 * 1 * 0.00144 = 0.008 seconds => 1 minimum Interval.
+
+Data Acquisition
+^^^^^^^^^^^^^^^^
+
+The Data Acquisition, Send to Controller and Interval settings are standard available configuration items. Send to Controller only when one or more Controllers are configured.
+
+Values
+^^^^^^
+
+The Values available for this sensor, are named ``Value1`` through ``Value4``, and can be adjusted as desired. The Formula field can be used to recalculate the shown results.
+
+.. Commands available
+.. ^^^^^^^^^^^^^^^^^^
+
+.. .. include:: P132_commands.repl
+
+.. Events
+.. ~~~~~~
+
+.. .. include:: P132_events.repl
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  2022-04-23 Initial release version.
+

docs/source/Plugin/_Plugin.rst

@@ -149,7 +149,8 @@ There are different released versions of ESP Easy:
    ":ref:`P124_page`","|P124_status|","P124"
    ":ref:`P125_page`","|P125_status|","P125"
    ":ref:`P126_page`","|P126_status|","P126"
-   ":ref:`P127_page`","|P127_status|","P125"
+   ":ref:`P127_page`","|P127_status|","P127"
+   ":ref:`P132_page`","|P132_status|","P132"
 
 
 Internal GPIO handling

docs/source/Plugin/_plugin_categories.repl

@@ -5,7 +5,7 @@
 .. |Plugin_Distance| replace:: :ref:`P110_page`, :ref:`P113_page`
 .. |Plugin_Dust| replace:: :ref:`P018_page`, :ref:`P053_page`, :ref:`P056_page`
 .. |Plugin_Energy_AC| replace:: :ref:`P076_page`, :ref:`P077_page`, :ref:`P078_page`, :ref:`P102_page`, :ref:`P108_page`
-.. |Plugin_Energy_DC| replace:: :ref:`P027_page`, :ref:`P085_page`, :ref:`P115_page`
+.. |Plugin_Energy_DC| replace:: :ref:`P027_page`, :ref:`P085_page`, :ref:`P115_page`, :ref:`P132_page`
 .. |Plugin_Energy_Heat| replace:: :ref:`P088_page`, :ref:`P093_page`
 .. |Plugin_Environment| replace:: :ref:`P004_page`, :ref:`P005_page`, :ref:`P006_page`, :ref:`P014_page`, :ref:`P024_page`, :ref:`P028_page`, :ref:`P030_page`, :ref:`P031_page`, :ref:`P032_page`, :ref:`P034_page`, :ref:`P039_page`, :ref:`P047_page`, :ref:`P051_page`, :ref:`P068_page`, :ref:`P069_page`, :ref:`P072_page`, :ref:`P103_page`, :ref:`P104_page`, :ref:`P105_page`, :ref:`P106_page`
 .. |Plugin_Extra_IO| replace:: :ref:`P011_page`, :ref:`P022_page`

docs/source/Plugin/_plugin_substitutions.repl

@@ -11,3 +11,4 @@
 .. include:: ../Plugin/_plugin_substitutions_p10x.repl
 .. include:: ../Plugin/_plugin_substitutions_p11x.repl
 .. include:: ../Plugin/_plugin_substitutions_p12x.repl
+.. include:: ../Plugin/_plugin_substitutions_p13x.repl

docs/source/Plugin/_plugin_substitutions_p13x.repl

@@ -0,0 +1,12 @@
+.. |P132_name| replace:: :cyan:`INA3221`
+.. |P132_type| replace:: :cyan:`Energy (DC)`
+.. |P132_typename| replace:: :cyan:`Energy (DC) - INA3221`
+.. |P132_porttype| replace:: `.`
+.. |P132_status| replace:: :yellow:`ENERGY`
+.. |P132_github| replace:: P132_INA3221.ino
+.. _P132_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P132_INA3221.ino
+.. |P132_usedby| replace:: `.`
+.. |P132_shortinfo| replace:: `3-channel I2C DC Voltage/Current sensor`
+.. |P132_maintainer| replace:: `tonhuisman`
+.. |P132_compileinfo| replace:: `.`
+.. |P132_usedlibraries| replace:: `.`

docs/source/Reference/SystemVariable.rst

@@ -46,17 +46,41 @@ More uses of these system variables can be seen in the rules section and formula
      - Current time if NTP is enabled (hh:mm:ss, hh:mm prior to v2.0).
      - 
    * - ``%systm_hm%``
-     - 01:23
+     - 1:23
      - Current time if NTP is enabled (hh:mm "old behavior").
      - 
+   * - ``%systm_hm_0%``
+     - 01:23
+     - Current time if NTP is enabled (0-prefixed if hour < 10).
+     - 
+   * - ``%systm_hm_sp%``
+     - ` 1:23`
+     - Current time if NTP is enabled (space-prefixed if hour < 10).
+     - 
    * - ``%systime_am%``
      - 1:23:54 AM
      - Current AM/PM time if NTP is enabled (hh:mm:ss xM).
      - 
+   * - ``%systime_am_0%``
+     - 01:23:54 AM
+     - Current AM/PM time if NTP is enabled (0-prefixed if hour < 10).
+     - 
+   * - ``%systime_am_sp%``
+     - ` 1:23:54 AM`
+     - Current AM/PM time if NTP is enabled (space-prefixed if hour < 10).
+     - 
    * - ``%systm_hm_am%``
      - 1:23 AM
      - Current AM/PM time if NTP is enabled (hh:mm:ss xM).
      - 
+   * - ``%systm_hm_am_0%``
+     - 01:23 AM
+     - Current AM/PM time if NTP is enabled (0-prefixed if hour < 10).
+     - 
+   * - ``%systm_hm_am_sp%``
+     - ` 1:23 AM`
+     - Current AM/PM time if NTP is enabled (space-prefixed if hour < 10).
+     - 
    * - ``%lcltime%``
      - 2020-03-16 01:23:54
      - Current date/time if NTP is enabled (YYYY-MM-DD hh:mm:ss).