letscontrolit · TD-er · Jan 31, 2024 · Jan 24, 2024 · Jan 25, 2024 · Jan 26, 2024
diff --git a/docs/source/Plugin/P166.rst b/docs/source/Plugin/P166.rst
@@ -0,0 +1,117 @@
+.. include:: ../Plugin/_plugin_substitutions_p16x.repl
+.. _P166_page:
+
+|P166_typename|
+==================================================
+
+|P166_shortinfo|
+
+Plugin details
+--------------
+
+Type: |P166_type|
+
+Name: |P166_name|
+
+Status: |P166_status|
+
+GitHub: |P166_github|_
+
+Maintainer: |P166_maintainer|
+
+Used libraries: |P166_usedlibraries|
+
+Description
+-----------
+
+The GP8403 DAC (Digital Analog Converter) has 2 output channels, can be configured for an output voltage range of 0-10V or 0-5V, has a 12 bit resolution (4096 steps) and works from a single 3.3V or 5V power source. When powering the module with 5V, a level converter should be used on the I2C lines, to protect the ESP and other I2C devices on the same bus. The outputs can supply up to 20 mA.
+
+.. image:: P166_DFRobot_GP8403_board.png
+
+(Image (c) DFRobot)
+
+Configuration
+-------------
+
+.. image:: P166_DeviceConfiguration.png
+
+* **Name**: Required by ESPEasy, must be unique among the list of available devices/tasks.
+
+* **Enabled**: The device can be disabled or enabled. When not enabled the device should not use any resources.
+
+I2C options
+^^^^^^^^^^^
+
+* **I2C Address**: The device supports 8 addresses, and by default comes configured for address ``0x5F``, as reflected in the available options:
+
+.. image:: P166_I2CAddressOptions.png
+
+Available addresses are in the range ``0x58`` to ``0x5F``.
+
+The available I2C 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`
+
+Device Settings
+^^^^^^^^^^^^^^^
+
+* **Output range**: Select the desired output voltage range:
+
+.. image:: P166_OutputRangeOptions.png
+
+Available options:
+
+* *0-5V*: The maximum available voltage is 5V. When not using a voltage > 5V, this would be the apropriate settings, both for accuracy, and to avoid the risk of applying up to 10V to an input that might not be able to handle that.
+
+* *0-10V*: (Preconfigured default) The maximum available voltage is 10V.
+
+The DAC does not support a different output range setting per output.
+
+The DAC can supply up to 20 mA per output, so the input or device that is connected to this output should be configured to not overload the output.
+
+* **Restore output on warm boot**: (Enabled by default) When the outputs are set to a specific value and the ESP unit is restarted, f.e. when updating the ESPEasy firmware, the output values will be restored. On cold boot, or after saving the settings, the configured Initial value per output will be set.
+
+* **Initial value output 0**:
+
+* **Initial value output 1**: The output value at startup, or after power-loss, can be configured here per output. The allowed range is 0-10V. Although the resolution is in milli Volt, the resolution of the DAC is limited to 12 bit (4096 steps). If a voltage is set here that exceeds the Output range (f.e. when set to 0-5V, and 7V is configured), the setting will **not** be applied!
+
+Preset values
+^^^^^^^^^^^^^
+
+* **Preset value 1..25**: This table allows to configure up to 25 named presets, where the name can be up to 16 characters long, and the voltage in range 0-10V. When all available inputs are filled, Submitting the page will add more inputs until the limit of 25 is reached.
+
+When leaving the *Name* field empty, that preset will not be saved, thus effectively deleted from the list.
+
+Data Acquisition
+^^^^^^^^^^^^^^^^
+
+This group of settings, **Single event with all values** and **Send to Controller** settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.
+
+* **Interval** By default, Interval will be set to 0 sec. The data will be collected and optionally sent to any configured controllers using this interval. When an output value is changed, the data will be sent to any configured controller, and an event will also be generated when the Rules are enabled (Tools/Advanced).
+
+Values
+^^^^^^
+
+The plugin provides the ``Output0`` and ``Output1`` values, analogue to the availabe output connections. A formula can be set to recalculate the displayed, and sent, value. The number of decimals can be set as desired, and defaults to 2.
+
+In selected builds, per Value is a **Stats** checkbox available, that when checked, gathers the data and presents recent data in a graph, as described here: :ref:`Task Value Statistics:  <Task Value Statistics>`
+
+Commands available
+^^^^^^^^^^^^^^^^^^
+
+.. include:: P166_commands.repl
+
+Get Config Values
+^^^^^^^^^^^^^^^^^
+
+Get Config Values retrieves values or settings from the plugin, and can be used in Rules, Display plugins, Formula's etc. The square brackets **are** part of the variable. Replace ``<taskname>`` by the **Name** of the task.
+
+.. include:: P166_config_values.repl
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  2024-01-30 Initial release version.
+
diff --git a/docs/source/Plugin/P166_DFRobot_GP8403_board.png b/docs/source/Plugin/P166_DFRobot_GP8403_board.png
diff --git a/docs/source/Plugin/P166_DeviceConfiguration.png b/docs/source/Plugin/P166_DeviceConfiguration.png
diff --git a/docs/source/Plugin/P166_I2CAddressOptions.png b/docs/source/Plugin/P166_I2CAddressOptions.png
diff --git a/docs/source/Plugin/P166_OutputRangeOptions.png b/docs/source/Plugin/P166_OutputRangeOptions.png
diff --git a/docs/source/Plugin/P166_commands.repl b/docs/source/Plugin/P166_commands.repl
@@ -0,0 +1,40 @@
+.. csv-table::
+    :header: "Command Syntax", "Extra information"
+    :widths: 20, 30
+
+    "
+    ``<ch>`` = Output channel, 0, 1 or 2 (both channels)
+    ","
+    When successfully changing an output value, the data will be sent to any configured Controller, and an event will also be generated when the Rules are enabled (Tools/Advanced).
+    "
+    "
+    ``gp8403,volt,<ch>,<value>``
+    ","
+    Set the output value for the channel(s) in volt. The range is determined by the configured Output range setting.
+    "
+    "
+    ``gp8403,mvolt,<ch>,<value>``
+    ","
+    Set the output value for the channel(s) in milli volt. The range is determined by the configured Output range setting.
+    "
+    "
+    ``gp8403,range,<5|10>``
+    ","
+    Set the output range to either 5 (0-5V) or 10 (0-10V). Is also set to the Device configuration, but not saved.
+
+    The range is applied to both channels, no separate configuration per channel supported by the chip.
+    "
+    "
+    ``gp8403,preset,<ch>,<name>``
+    ","
+    Set the output value for the channel(s) to the value configured for the preset stored with ``<name>``.
+
+    The value is range-checked before it is applied, so when configured for Output range 0-5V, a preset of 7V will be ignored.
+
+    When using duplicate names, the first matched preset will be used.
+    "
+    "
+    ``gp8403,init,<ch>``
+    ","
+    Set the output value for the channel(s) to the configured initial value(s). When both channels are addressed (2), each will get its own configured value.
+    "
diff --git a/docs/source/Plugin/P166_config_values.repl b/docs/source/Plugin/P166_config_values.repl
@@ -0,0 +1,24 @@
+.. csv-table::
+    :header: "Config value", "Information"
+    :widths: 20, 30
+
+    "
+    ``[<taskname>#preset<X>]``
+    ","
+    Returns the numbered preset value ``<X>``, range ``preset1``..``preset25``, as shown in the configuration. Only configured values, having a name, can be retrieved.
+    "
+    "
+    ``[<taskname>#initial0]``
+    ","
+    Returns the configured initial voltage for output 0.
+    "
+    "
+    ``[<taskname>#initial1]``
+    ","
+    Returns the configured initial voltage for output 1.
+    "
+    "
+    ``[<taskname>#range]``
+    ","
+    Returns the configured Output range value 5 (0-5V) or 10 (0-10V)
+    "
diff --git a/docs/source/Plugin/_Plugin.rst b/docs/source/Plugin/_Plugin.rst
@@ -386,6 +386,7 @@ There are different released versions of ESP Easy:
    ":ref:`P153_page`","|P153_status|","P153"
    ":ref:`P154_page`","|P154_status|","P154"
    ":ref:`P159_page`","|P159_status|","P159"
+   ":ref:`P166_page`","|P166_status|","P166"
 
 
 Internal GPIO handling

diff --git a/docs/source/Plugin/_plugin_categories.repl b/docs/source/Plugin/_plugin_categories.repl
@@ -22,7 +22,7 @@
 .. |Plugin_Light_Lux| replace:: :ref:`P010_page`, :ref:`P015_page`, :ref:`P074_page`
 .. |Plugin_Motor| replace:: :ref:`P048_page`, :ref:`P079_page`, :ref:`P098_page`
 .. |Plugin_Notify| replace:: :ref:`P055_page`, :ref:`P065_page`
-.. |Plugin_Output| replace:: :ref:`P029_page`, :ref:`P038_page`, :ref:`P041_page`, :ref:`P042_page`, :ref:`P043_page`, :ref:`P070_page`, :ref:`P124_page`, :ref:`P126_page`, :ref:`P128_page`, :ref:`P152_page`
+.. |Plugin_Output| replace:: :ref:`P029_page`, :ref:`P038_page`, :ref:`P041_page`, :ref:`P042_page`, :ref:`P043_page`, :ref:`P070_page`, :ref:`P124_page`, :ref:`P126_page`, :ref:`P128_page`, :ref:`P152_page`, :ref:`P166_page`
 .. |Plugin_Position| replace:: :ref:`P082_page`, :ref:`P121_page`
 .. |Plugin_PowerMgt| replace:: :ref:`P137_page`, :ref:`P138_page`
 .. |Plugin_Presence| replace:: :ref:`P159_page`

diff --git a/docs/source/Plugin/_plugin_substitutions.repl b/docs/source/Plugin/_plugin_substitutions.repl
@@ -14,3 +14,4 @@
 .. include:: ../Plugin/_plugin_substitutions_p13x.repl
 .. include:: ../Plugin/_plugin_substitutions_p14x.repl
 .. include:: ../Plugin/_plugin_substitutions_p15x.repl
+.. include:: ../Plugin/_plugin_substitutions_p16x.repl
diff --git a/docs/source/Plugin/_plugin_substitutions_p16x.repl b/docs/source/Plugin/_plugin_substitutions_p16x.repl
@@ -0,0 +1,12 @@
+.. |P166_name| replace:: :cyan:`GP8403 Dual channel DAC 0-10V`
+.. |P166_type| replace:: :cyan:`Output`
+.. |P166_typename| replace:: :cyan:`Output - GP8403 Dual channel DAC 0-10V`
+.. |P166_porttype| replace:: `.`
+.. |P166_status| replace:: :yellow:`COLLECTION G`
+.. |P166_github| replace:: P166_GP8403.ino
+.. _P166_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P166_GP8403.ino
+.. |P166_usedby| replace:: `.`
+.. |P166_shortinfo| replace:: `GP8403 Dual channel DAC 0-10V`
+.. |P166_maintainer| replace:: `tonhuisman`
+.. |P166_compileinfo| replace:: `.`
+.. |P166_usedlibraries| replace:: `modified version of DFRobot_GP8403`
diff --git a/docs/source/Reference/Command.rst b/docs/source/Reference/Command.rst
@@ -795,6 +795,11 @@ P159 :ref:`P159_page`
 
 .. include:: ../Plugin/P159_commands.repl
 
+P166 :ref:`P166_page`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: ../Plugin/P166_commands.repl
+
 .. .. *** Insert regular plugin commands above this remark! ***
 
 .. _AdafruitGFX Helper commands: