diff --git a/docs/source/Plugin/P124.rst b/docs/source/Plugin/P124.rst new file mode 100644 index 000000000..c52a56f6f --- /dev/null +++ b/docs/source/Plugin/P124.rst @@ -0,0 +1,144 @@ +.. include:: ../Plugin/_plugin_substitutions_p12x.repl +.. _P124_page: + +|P124_typename| +================================================== + +|P124_shortinfo| + +Plugin details +-------------- + +Type: |P124_type| + +Name: |P124_name| + +Status: |P124_status| + +GitHub: |P124_github|_ + +Maintainer: |P124_maintainer| + +Used libraries: |P124_usedlibraries| + +Description +----------- + +This plugin is the interface to the Seeed Studio I2C multi relay boards (either solid state or mechanical). + +Each channel can be switched separately, or multiple relays at once, by sending the appropriate commands (see below). + +Supported hardware +------------------ + +* `Seeed Studio Grove SPDT 4 Channel Relay`_ +* `Seeed Studio Grove 2 Channel Solid State Relay`_ +* `Seeed Studio Grove 4 Channel Solid State Relay`_ +* `Seeed Studio Grove 8 Channel Solid State Relay`_ + +.. _Seeed Studio Grove SPDT 4 Channel Relay: https://wiki.seeedstudio.com/Grove-4-Channel_SPDT_Relay/ +.. _Seeed Studio Grove 2 Channel Solid State Relay: https://wiki.seeedstudio.com/Grove-2-Channel_Solid_State_Relay/ +.. _Seeed Studio Grove 4 Channel Solid State Relay: https://wiki.seeedstudio.com/Grove-4-Channel_Solid_State_Relay/ +.. _Seeed Studio Grove 8 Channel Solid State Relay: https://wiki.seeedstudio.com/Grove-8-Channel_Solid_State_Relay/ + +Configuration +------------- + +.. image:: P124_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 device is using. + +.. image:: P124_I2CAddresses.png + :alt: List of supported I2C addresses + +* **Change I2C address of board**: These boards allow to change their I2C address. Once changed the address will be retained in the board non-volatile memory, until changed again. Currently addresses ``0x11`` to ``0x18`` are supported. + +The procedure to change the address is: + +* Connect only 1 of these boards to the I2C bus (other I2C devices *can* stay connected) +* Select the current board address in the **I2C Address** field. Use the Tools / I2C Scanner feature to retrieve the current board address, if needed. + +.. .. comment + +* Enable the **Change I2C address of board** option. +* Submit the page (saving the settings). This will increment the board' I2C address to the next one in the list. +* Optional: Use the Tools / I2C Scanner feature to verify that the board now has the next address. +* The **I2C Address** of the task will be updated to the new address. +* Repeat above steps until the desired address is set. After reaching the highest address, the default address ``0x11`` will be set. +* Save the settings using the Submit button. + +After changing the address, a next board can be connected that uses another board address, most likely ``0x11``. Each board will require an additional task to be configured. + +Device Settings +^^^^^^^^^^^^^^^ + +* **Number of relays**: Select the number of relays on the board connected. + +.. image:: P124_NumberOfRelaysOptions.png + :alt: Number of relays selection + +When changing the number of relays, the page will be submitted and the settings saved. + +* **Initialize relays on startup**: To initialize the relay on/off state after startup of the plugin, this option can be set to Yes. When changing the setting the page will be submitted and the settings saved. + +.. image:: P124_InitializeRelaysYes.png + :alt: Initialize relays on startup enabled + +* **Apply initial state always**: Off by default, then the initialization state will be sent only once after a restart of the ESP unit. When Enabled the initialization state will be sent on every start of the plugin, like after a Submit of the settings page. + +* **Relay # initial state (on/off)**: The on or off state the relay should be set to on initialization of the plugin. Will show a checkbox for the number of relays configured (2, 4 or 8). + +.. .. comment + +* **Reset relays on exit**: To set the relay on/off state when the plugin is disabled, this option can be set to Yes. When changing the setting the page will be submitted and the settings saved. + +.. image:: P124_ResetRelaysYes.png + :alt: Reset relays on exit enabled + +* **Relay # exit-state (on/off)**: The on or off state the relay should be set to when the plugin is disabled. Will show a checkbox for the number of relays configured (2, 4 or 8). + +.. note:: This will also be applied when Submitting the device settings page! + +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 +^^^^^^ + +There is only 1 value available for this sensor, with the default name ``State``. + +Commands available +------------------ + +.. include:: P124_commands.repl + +.. Events +.. ~~~~~~ + +.. .. include:: P124_events.repl + +Change log +---------- + +.. versionchanged:: 2.0 + ... + + |added| + 2021-11-19 Initial release version. + + + + + diff --git a/docs/source/Plugin/P124_DeviceConfiguration.png b/docs/source/Plugin/P124_DeviceConfiguration.png new file mode 100644 index 000000000..5d56221af Binary files /dev/null and b/docs/source/Plugin/P124_DeviceConfiguration.png differ diff --git a/docs/source/Plugin/P124_I2CAddresses.png b/docs/source/Plugin/P124_I2CAddresses.png new file mode 100644 index 000000000..7a43124e3 Binary files /dev/null and b/docs/source/Plugin/P124_I2CAddresses.png differ diff --git a/docs/source/Plugin/P124_InitializeRelaysYes.png b/docs/source/Plugin/P124_InitializeRelaysYes.png new file mode 100644 index 000000000..ea156edcc Binary files /dev/null and b/docs/source/Plugin/P124_InitializeRelaysYes.png differ diff --git a/docs/source/Plugin/P124_NumberOfRelaysOptions.png b/docs/source/Plugin/P124_NumberOfRelaysOptions.png new file mode 100644 index 000000000..d11d7a56c Binary files /dev/null and b/docs/source/Plugin/P124_NumberOfRelaysOptions.png differ diff --git a/docs/source/Plugin/P124_ResetRelaysYes.png b/docs/source/Plugin/P124_ResetRelaysYes.png new file mode 100644 index 000000000..ec0560021 Binary files /dev/null and b/docs/source/Plugin/P124_ResetRelaysYes.png differ diff --git a/docs/source/Plugin/P124_commands.repl b/docs/source/Plugin/P124_commands.repl new file mode 100644 index 000000000..734f03235 --- /dev/null +++ b/docs/source/Plugin/P124_commands.repl @@ -0,0 +1,31 @@ +.. csv-table:: + :header: "Command Syntax", "Extra information" + :widths: 20, 30 + + " + + | ``multirelay,on,`` + + "," + + | Switch on the relay at the channel given. Range is 1..8, but limited to the number the plugin is configured for. + + " + " + + | ``multirelay,off,`` + + "," + + | Switch off the relay at the channel given. Range is 1..8, but limited to the number the plugin is configured for. + + " + " + + | ``multirelay,set,`` + + "," + + | Switch on and off according to the bitmap provided, in 8..1 order. The bitmap can be given in decimal (``nn``, 1-3 digits, ``0`` to ``9``), hexadecimal (``0xnn``, 1 or 2 digits, ``0`` to ``f``) or binary (``0bnnnnnnnn``, 1 to 8 digits, ``0`` or ``1``) notation. + + " diff --git a/docs/source/Plugin/_Plugin.rst b/docs/source/Plugin/_Plugin.rst index a643dda81..5ddba4fdd 100644 --- a/docs/source/Plugin/_Plugin.rst +++ b/docs/source/Plugin/_Plugin.rst @@ -140,6 +140,7 @@ There are different released versions of ESP Easy: ":ref:`P113_page`","|P113_status|","P113" ":ref:`P114_page`","|P114_status|","P114" ":ref:`P115_page`","|P115_status|","P115" + ":ref:`P124_page`","|P124_status|","P124" Internal GPIO handling diff --git a/docs/source/Plugin/_plugin_categories.repl b/docs/source/Plugin/_plugin_categories.repl index 30917de4a..59bb7950a 100644 --- a/docs/source/Plugin/_plugin_categories.repl +++ b/docs/source/Plugin/_plugin_categories.repl @@ -19,7 +19,7 @@ .. |Plugin_Light_Lux| replace:: :ref:`P010_page`, :ref:`P015_page`, :ref:`P074_page` .. |Plugin_Motor| replace:: :ref:`P048_page`, :ref:`P079_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` +.. |Plugin_Output| replace:: :ref:`P029_page`, :ref:`P038_page`, :ref:`P041_page`, :ref:`P042_page`, :ref:`P043_page`, :ref:`P070_page`, :ref:`P124_page` .. |Plugin_Position| replace:: :ref:`P013_page`, :ref:`P082_page` .. |Plugin_Regulator| replace:: :ref:`P021_page` .. |Plugin_RFID| replace:: :ref:`P008_page`, :ref:`P017_page`, :ref:`P040_page`, :ref:`P111_page` diff --git a/docs/source/Plugin/_plugin_substitutions.repl b/docs/source/Plugin/_plugin_substitutions.repl index 5b21be98c..9f0022404 100644 --- a/docs/source/Plugin/_plugin_substitutions.repl +++ b/docs/source/Plugin/_plugin_substitutions.repl @@ -10,3 +10,4 @@ .. include:: ../Plugin/_plugin_substitutions_p09x.repl .. include:: ../Plugin/_plugin_substitutions_p10x.repl .. include:: ../Plugin/_plugin_substitutions_p11x.repl +.. include:: ../Plugin/_plugin_substitutions_p12x.repl diff --git a/docs/source/Plugin/_plugin_substitutions_p12x.repl b/docs/source/Plugin/_plugin_substitutions_p12x.repl new file mode 100644 index 000000000..5288de500 --- /dev/null +++ b/docs/source/Plugin/_plugin_substitutions_p12x.repl @@ -0,0 +1,12 @@ +.. |P124_name| replace:: :cyan:`MultiRelay` +.. |P124_type| replace:: :cyan:`Output` +.. |P124_typename| replace:: :cyan:`Output - I2C Multi Relay` +.. |P124_porttype| replace:: `.` +.. |P124_status| replace:: :yellow:`TESTING D` +.. |P124_github| replace:: P124_MultiTelay.ino +.. _P124_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P124_MyltiRelay.ino +.. |P124_usedby| replace:: `.` +.. |P124_shortinfo| replace:: `Seeed Studio I2C Multi Relay boards` +.. |P124_maintainer| replace:: `tonhuisman` +.. |P124_compileinfo| replace:: `.` +.. |P124_usedlibraries| replace:: `https://github.com/Seeed-Studio/Multi_Channel_Relay_Arduino_Library (modified local copy)`