Skip to content

Commit 0e0145e

Browse files
TD-erTD-er
authored
Merge pull request #4952 from tonhuisman/feature/P166-Add-plugin-gp8403-dac-0-10V
[P166] Add plugin GP8403 DAC Dual channel 0-10V
2 parents 8e86a55 + 88e05ed commit 0e0145e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+2986
-60
lines changed

‎docs/source/Plugin/P166.rst

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
.. include:: ../Plugin/_plugin_substitutions_p16x.repl
2+
.. _P166_page:
3+
4+
|P166_typename|
5+
==================================================
6+
7+
|P166_shortinfo|
8+
9+
Plugin details
10+
--------------
11+
12+
Type: |P166_type|
13+
14+
Name: |P166_name|
15+
16+
Status: |P166_status|
17+
18+
GitHub: |P166_github|_
19+
20+
Maintainer: |P166_maintainer|
21+
22+
Used libraries: |P166_usedlibraries|
23+
24+
Description
25+
-----------
26+
27+
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.
28+
29+
.. image:: P166_DFRobot_GP8403_board.png
30+
31+
(Image (c) DFRobot)
32+
33+
Configuration
34+
-------------
35+
36+
.. image:: P166_DeviceConfiguration.png
37+
38+
* **Name**: Required by ESPEasy, must be unique among the list of available devices/tasks.
39+
40+
* **Enabled**: The device can be disabled or enabled. When not enabled the device should not use any resources.
41+
42+
I2C options
43+
^^^^^^^^^^^
44+
45+
* **I2C Address**: The device supports 8 addresses, and by default comes configured for address ``0x5F``, as reflected in the available options:
46+
47+
.. image:: P166_I2CAddressOptions.png
48+
49+
Available addresses are in the range ``0x58`` to ``0x5F``.
50+
51+
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`
52+
53+
Device Settings
54+
^^^^^^^^^^^^^^^
55+
56+
* **Output range**: Select the desired output voltage range:
57+
58+
.. image:: P166_OutputRangeOptions.png
59+
60+
Available options:
61+
62+
* *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.
63+
64+
* *0-10V*: (Preconfigured default) The maximum available voltage is 10V.
65+
66+
The DAC does not support a different output range setting per output.
67+
68+
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.
69+
70+
* **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.
71+
72+
* **Initial value output 0**:
73+
74+
* **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!
75+
76+
Preset values
77+
^^^^^^^^^^^^^
78+
79+
* **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.
80+
81+
When leaving the *Name* field empty, that preset will not be saved, thus effectively deleted from the list.
82+
83+
Data Acquisition
84+
^^^^^^^^^^^^^^^^
85+
86+
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.
87+
88+
* **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).
89+
90+
Values
91+
^^^^^^
92+
93+
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.
94+
95+
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>`
96+
97+
Commands available
98+
^^^^^^^^^^^^^^^^^^
99+
100+
.. include:: P166_commands.repl
101+
102+
Get Config Values
103+
^^^^^^^^^^^^^^^^^
104+
105+
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.
106+
107+
.. include:: P166_config_values.repl
108+
109+
Change log
110+
----------
111+
112+
.. versionchanged:: 2.0
113+
...
114+
115+
|added|
116+
2024-01-30 Initial release version.
117+

‎docs/source/Plugin/P166_DFRobot_GP8403_board.png

71 KB
Loading

‎docs/source/Plugin/P166_DeviceConfiguration.png

59.6 KB
Loading

‎docs/source/Plugin/P166_I2CAddressOptions.png

44.2 KB
Loading

‎docs/source/Plugin/P166_OutputRangeOptions.png

14.5 KB
Loading

‎docs/source/Plugin/P166_commands.repl

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
.. csv-table::
2+
:header: "Command Syntax", "Extra information"
3+
:widths: 20, 30
4+
5+
"
6+
``<ch>`` = Output channel, 0, 1 or 2 (both channels)
7+
","
8+
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).
9+
"
10+
"
11+
``gp8403,volt,<ch>,<value>``
12+
","
13+
Set the output value for the channel(s) in volt. The range is determined by the configured Output range setting.
14+
"
15+
"
16+
``gp8403,mvolt,<ch>,<value>``
17+
","
18+
Set the output value for the channel(s) in milli volt. The range is determined by the configured Output range setting.
19+
"
20+
"
21+
``gp8403,range,<5|10>``
22+
","
23+
Set the output range to either 5 (0-5V) or 10 (0-10V). Is also set to the Device configuration, but not saved.
24+
25+
The range is applied to both channels, no separate configuration per channel supported by the chip.
26+
"
27+
"
28+
``gp8403,preset,<ch>,<name>``
29+
","
30+
Set the output value for the channel(s) to the value configured for the preset stored with ``<name>``.
31+
32+
The value is range-checked before it is applied, so when configured for Output range 0-5V, a preset of 7V will be ignored.
33+
34+
When using duplicate names, the first matched preset will be used.
35+
"
36+
"
37+
``gp8403,init,<ch>``
38+
","
39+
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.
40+
"

‎docs/source/Plugin/P166_config_values.repl

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.. csv-table::
2+
:header: "Config value", "Information"
3+
:widths: 20, 30
4+
5+
"
6+
``[<taskname>#preset<X>]``
7+
","
8+
Returns the numbered preset value ``<X>``, range ``preset1``..``preset25``, as shown in the configuration. Only configured values, having a name, can be retrieved.
9+
"
10+
"
11+
``[<taskname>#initial0]``
12+
","
13+
Returns the configured initial voltage for output 0.
14+
"
15+
"
16+
``[<taskname>#initial1]``
17+
","
18+
Returns the configured initial voltage for output 1.
19+
"
20+
"
21+
``[<taskname>#range]``
22+
","
23+
Returns the configured Output range value 5 (0-5V) or 10 (0-10V)
24+
"

‎docs/source/Plugin/_Plugin.rst

+1
Original file line numberDiff line numberDiff line change
@@ -386,6 +386,7 @@ There are different released versions of ESP Easy:
386386
":ref:`P153_page`","|P153_status|","P153"
387387
":ref:`P154_page`","|P154_status|","P154"
388388
":ref:`P159_page`","|P159_status|","P159"
389+
":ref:`P166_page`","|P166_status|","P166"
389390

390391

391392
Internal GPIO handling

‎docs/source/Plugin/_plugin_categories.repl

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
.. |Plugin_Light_Lux| replace:: :ref:`P010_page`, :ref:`P015_page`, :ref:`P074_page`
2323
.. |Plugin_Motor| replace:: :ref:`P048_page`, :ref:`P079_page`, :ref:`P098_page`
2424
.. |Plugin_Notify| replace:: :ref:`P055_page`, :ref:`P065_page`
25-
.. |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`
25+
.. |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`
2626
.. |Plugin_Position| replace:: :ref:`P082_page`, :ref:`P121_page`
2727
.. |Plugin_PowerMgt| replace:: :ref:`P137_page`, :ref:`P138_page`
2828
.. |Plugin_Presence| replace:: :ref:`P159_page`

‎docs/source/Plugin/_plugin_substitutions.repl

+1
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@
1414
.. include:: ../Plugin/_plugin_substitutions_p13x.repl
1515
.. include:: ../Plugin/_plugin_substitutions_p14x.repl
1616
.. include:: ../Plugin/_plugin_substitutions_p15x.repl
17+
.. include:: ../Plugin/_plugin_substitutions_p16x.repl

‎docs/source/Plugin/_plugin_substitutions_p16x.repl

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.. |P166_name| replace:: :cyan:`GP8403 Dual channel DAC 0-10V`
2+
.. |P166_type| replace:: :cyan:`Output`
3+
.. |P166_typename| replace:: :cyan:`Output - GP8403 Dual channel DAC 0-10V`
4+
.. |P166_porttype| replace:: `.`
5+
.. |P166_status| replace:: :yellow:`COLLECTION G`
6+
.. |P166_github| replace:: P166_GP8403.ino
7+
.. _P166_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P166_GP8403.ino
8+
.. |P166_usedby| replace:: `.`
9+
.. |P166_shortinfo| replace:: `GP8403 Dual channel DAC 0-10V`
10+
.. |P166_maintainer| replace:: `tonhuisman`
11+
.. |P166_compileinfo| replace:: `.`
12+
.. |P166_usedlibraries| replace:: `modified version of DFRobot_GP8403`

‎docs/source/Reference/Command.rst

+5
Original file line numberDiff line numberDiff line change
@@ -795,6 +795,11 @@ P159 :ref:`P159_page`
795795

796796
.. include:: ../Plugin/P159_commands.repl
797797

798+
P166 :ref:`P166_page`
799+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
800+
801+
.. include:: ../Plugin/P166_commands.repl
802+
798803
.. .. *** Insert regular plugin commands above this remark! ***
799804
800805
.. _AdafruitGFX Helper commands:

0 commit comments

Comments
 (0)