Merge pull request #3851 from tonhuisman/feature/p124-i2c-multi-relay…

…-plugin [P124] Add plugin I2C Multi Relay
letscontrolit · Dec 12, 2021 · 2f8bfca · 2f8bfca · clumsy-stefan · Dec 30, 2021
2 parents 5f055eb + aad8e44
commit 2f8bfca
Show file tree

Hide file tree

Showing 32 changed files with 1,370 additions and 4 deletions.
diff --git a/docs/source/Plugin/P124.rst b/docs/source/Plugin/P124.rst
@@ -0,0 +1,147 @@
+.. 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!
+
+* **Loop Channel/Get on read**: When enabled, will update the Channel and Get values with the selected channel and its current state (0=off, 1=on). The channel will be incremented each interval (read action).
+
+
+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 ``State``, holding the decimal value of the current channel_bitmap, ``Channel`` and ``Get``, showing the channel and its on/off state (1/0) of the last ``multirelay,get,<channel>`` command or when **Loop Channel/Get on read** is checked.
+
+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
diff --git a/docs/source/Plugin/P124_I2CAddresses.png b/docs/source/Plugin/P124_I2CAddresses.png
diff --git a/docs/source/Plugin/P124_InitializeRelaysYes.png b/docs/source/Plugin/P124_InitializeRelaysYes.png
diff --git a/docs/source/Plugin/P124_NumberOfRelaysOptions.png b/docs/source/Plugin/P124_NumberOfRelaysOptions.png
diff --git a/docs/source/Plugin/P124_ResetRelaysYes.png b/docs/source/Plugin/P124_ResetRelaysYes.png
diff --git a/docs/source/Plugin/P124_commands.repl b/docs/source/Plugin/P124_commands.repl
@@ -0,0 +1,49 @@
+.. csv-table::
+    :header: "Command Syntax", "Extra information"
+    :widths: 20, 30
+
+    "
+
+    | ``multirelay,on,<channel>``
+
+    ","
+
+    | Switch on the relay at the channel given. Range is 1..8, but limited to the number the plugin is configured for.
+
+    "
+    "
+
+    | ``multirelay,off,<channel>``
+
+    ","
+
+    | Switch off the relay at the channel given. Range is 1..8, but limited to the number the plugin is configured for.
+
+    "
+    "
+
+    | ``multirelay,set,<channel_bitmap>``
+
+    ","
+
+    | 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.
+
+    "
+    "
+
+    | ``multirelay,get,<channel>``
+
+    ","
+
+    | Get the current state of the requested channel (checked for being in range 1 to the number of relays configured), and put that in the Channel and Get values, so it will be available to rules or a configured controller.
+
+    "
+    "
+
+    | ``multirelay,loop,0|1``
+
+    ","
+
+    | Disable or enable getting the next channel state on every Interval read. Corresponds to the **Loop Channel/Get on read** option in the device settings, but does not check/uncheck that setting.
+
+    "
diff --git a/docs/source/Plugin/_Plugin.rst b/docs/source/Plugin/_Plugin.rst
@@ -141,6 +141,7 @@ There are different released versions of ESP Easy:
    ":ref:`P114_page`","|P114_status|","P114"
    ":ref:`P115_page`","|P115_status|","P115"
    ":ref:`P117_page`","|P117_status|","P117"
+   ":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
@@ -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
@@ -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
@@ -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)`
diff --git a/docs/source/Reference/Command.rst b/docs/source/Reference/Command.rst
@@ -664,8 +664,12 @@ P115 :ref:`P115_page`
 
 .. include:: ../Plugin/P115_commands.repl
 
-
 P117 :ref:`P117_page`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. include:: ../Plugin/P117_commands.repl
+
+P124 :ref:`P124_page`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: ../Plugin/P124_commands.repl
diff --git a/lib/Multi_Channel_Relay_Arduino_Library/.gitlab-ci.yml b/lib/Multi_Channel_Relay_Arduino_Library/.gitlab-ci.yml
@@ -0,0 +1,8 @@
+build:
+  tags:
+    - nas
+  script:
+    - wget -c https://files.seeedstudio.com/arduino/seeed-arduino-ci.sh
+    - chmod +x seeed-arduino-ci.sh
+    - bash $PWD/seeed-arduino-ci.sh test
+
diff --git a/lib/Multi_Channel_Relay_Arduino_Library/.travis.yml b/lib/Multi_Channel_Relay_Arduino_Library/.travis.yml
@@ -0,0 +1,21 @@
+
+language: generic
+dist: bionic
+sudo: false
+cache:
+  directories:
+    - ~/arduino_ide
+    - ~/.arduino15/packages/
+
+before_install:
+   - wget -c https://files.seeedstudio.com/arduino/seeed-arduino-ci.sh
+
+script:
+   - chmod +x seeed-arduino-ci.sh
+   - cat $PWD/seeed-arduino-ci.sh
+   - bash $PWD/seeed-arduino-ci.sh test
+
+notifications:
+  email:
+    on_success: change
+    on_failure: change
diff --git a/lib/Multi_Channel_Relay_Arduino_Library/LICENSE b/lib/Multi_Channel_Relay_Arduino_Library/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Seeed Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/lib/Multi_Channel_Relay_Arduino_Library/README.md b/lib/Multi_Channel_Relay_Arduino_Library/README.md
@@ -0,0 +1,84 @@
+# Multi_Channel_Relay_Arduino_Library  [![Build Status](https://travis-ci.com/Seeed-Studio/Multi_Channel_Relay_Arduino_Library.svg?branch=master)](https://travis-ci.com/Seeed-Studio/Multi_Channel_Relay_Arduino_Library)
+This is the Arduino library for Seeed multi channel relay. 
+
+<!-- <img src= width=400> -->
+
+<!-- [Grove - OLED Display 0.96"](https://www.seeedstudio.com/s/Grove-OLED-Display-0.96%22-p-781.html) -->
+
+<!-- Description for this product -->
+
+### How to use this library
+you can download from Arduino Library Manager or directlly download from this repository.
+Connect the 8-channel Solid state relay v1.0 to Arduino board's I2C port, compile and upload four_channel_relay_control.ino. Open the serial monitor the relay should go as expected some massage should show as below:
+
+```
+Channel 1 on
+Channel 2 on
+Channel 3 on
+Channel 4 on
+Turn all channels on, State: 1111
+Turn 1 3 channels on, State: 101
+Turn 2 4 channels on, State: 1010
+Turn off all channels, State: 0
+```
+
+- Upload eight_channel_relay_control.ino, open the serial monitor and show the below logs:
+
+```
+Channel 1 on
+Channel 2 on
+Channel 3 on
+Channel 4 on
+Channel 5 on
+Channel 6 on
+Channel 7 on
+Channel 8 on
+Turn all channels on, State: 11111111
+Turn 1 3 5 7 channels on, State: 1010101
+Turn 2 4 6 8 channels on, State: 10101010
+Turn off all channels, State: 0
+
+```
+
+- This module can be set I2C address by software, open change_i2c_address.ino modify new_i2c_address as you want; compile and upload the sketch, open the serial monitor and show the below logs:
+
+```
+Scanning...
+I2C device found at address 0x11  !
+Found 1 devices
+Address 0x21 has been saved to flash.
+```
+
+- Read firmware version of the module by example read_firmware_version.ino. Serial logs as below:
+
+```
+firmware version: 0x1
+```
+
+### Functionalities
+- The relay board is an I2C device, device address is changeable, refer to **changeI2CAddress(uint8_t new_addr, uint8_t old_addr)** .
+- Use **getChannelState()** to know the state of every channel.
+- Use **getFirmwareVersion()** to recognize firmware burn in the on board MCU.
+- Use **channelCtrl(uint8_t state)** to change all channel immediately, the **state** parameter represents channel 1 to 8.  
+- Use **turn_on_channel(uint8_t channel)** to turn on single channel.
+- Use **turn_off_channel(uint8_t channel)**	to turn off single channel.
+- External functionality **scanI2CDevice()**, use for scan device address.
+
+
+<!-- For more information, please refer to [Grove_OLED_Display_128X64 wiki][1] -->
+
+----
+This software is written by lambor for seeed studio and is licensed under The MIT License.<br>
+
+Contributing to this software is warmly welcomed. You can do this basically by<br>
+[forking](https://help.github.com/articles/fork-a-repo), committing modifications and then [pulling requests](https://help.github.com/articles/using-pull-requests) (follow the links above<br>
+for operating guide). Adding change log and your contact into file header is encouraged.<br>
+Thanks for your contribution.
+
+Seeed is a hardware innovation platform for makers to grow inspirations into differentiating products. By working closely with technology providers of all scale, Seeed provides accessible technologies with quality, speed and supply chain knowledge. When prototypes are ready to iterate, Seeed helps productize 1 to 1,000 pcs using in-house engineering, supply chain management and agile manufacture forces. Seeed also team up with incubators, Chinese tech ecosystem, investors and distribution channels to portal Maker startups beyond.
+
+
+[1]:http://wiki.seeedstudio.com/Grove-OLED_Display_0.96inch/
+
+
+<!-- [![Analytics](https://ga-beacon.appspot.com/UA-46589105-3/OLED_Display_128X64)](https://github.com/igrigorik/ga-beacon) -->