Merge pull request #5218 from TD-er/feature/P178_LU9685

[LU9685] Add P178_LU9685  (#5216)

docs/source/Plugin/P178.rst

@@ -0,0 +1,88 @@
+.. include:: ../Plugin/_plugin_substitutions_p17x.repl
+.. _P178_page:
+
+|P178_typename|
+==================================================
+
+|P178_shortinfo|
+
+Plugin details
+--------------
+
+Type: |P178_type|
+
+Name: |P178_name|
+
+Status: |P178_status|
+
+GitHub: |P178_github|_
+
+Maintainer: |P178_maintainer|
+
+Used libraries: |P178_usedlibraries|
+
+Introduction
+------------
+
+The ``LU9685`` is being sold on a PCB as a 16 channel servo controller by various sellers like AliExpress, E-bay, etc.
+However the chip itself is capable of addressing upto 20 servos.
+
+These "16-channel"-boards resemble the design of many older PCA9685 boards and many sellers claim this ``LU9685`` is a direct replacement for the ``PCA9685``.
+However, these are quite different chips.
+
+The ``LU9685`` is specifically aimed to be used as a servo controller chip as it can only set the PWM pulse per pin between 0.5 ms .. 2.5 ms.
+
+The PWM frequency can be set from 20 Hz - 300 Hz.
+
+Supported hardware
+------------------
+
+|P178_usedby|
+
+Configuration
+-------------
+
+* **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
+^^^^^^^^^^^
+
+The available I2C settings here depend on the build used.
+
+Device Settings
+^^^^^^^^^^^^^^^
+
+* **PWM Frequency**: The frequency of sending the PWM pulses. Range 20 .. 255 Hz.
+
+
+Commands available
+^^^^^^^^^^^^^^^^^^
+
+.. include:: P178_commands.repl
+
+.. Events
+.. ~~~~~~
+
+.. .. include:: P178_events.repl
+
+Change log
+----------
+
+.. versionchanged:: 2.0
+  ...
+
+  |added|
+  Major overhaul for 2.0 release.
+
+.. versionadded:: 1.0
+  ...
+
+  |added|
+  Initial release version.
+
+
+
+
+

docs/source/Plugin/P178_commands.repl

@@ -0,0 +1,65 @@
+.. csv-table::
+  :header: "Command", "Extra information"
+  :widths: 20, 30
+
+  "
+  ``lu9685,servo,<pin>,<angle>``
+
+  ``[<taskname>].lu9685,servo,<pin>,<angle>``
+
+  pin: 0 ... 19 or ``all``
+
+  angle: 0 ... 180  (``-1`` will disable the output on the given pin)
+
+  ","
+  **Set specified pin to output a pulse duration for a servo**
+
+  The pulse width from 0.5 msec ... 2.5 msec is interpreted by a servo as an angle from 0 ... 180 degree.
+  Some servos have a range of 270 degree. However the input value for this command is still from 0 ... 180.
+
+  When ``all`` is used as pin, these commands refer to all pins on the addressed LU9685.
+
+  Examples: 
+
+  * ``lu9685,servo,all,123``
+  * ``lu9685,servo,1,123``
+  "
+  "
+  ``lu9685,enable,<pin>``
+
+  ``lu9685,disable,<pin>``
+
+  ``[<taskname>].lu9685,enable,<pin>``
+
+  ``[<taskname>].lu9685,disable,<pin>``
+
+  pin: 0 ... 19 or ``all``
+  ","
+  **Enable or disable pulse output on specified pin(s)** 
+
+  ``enable`` will restore the last set 'angle' to be output on the specified pin(s).
+
+  ``disable`` will stop outputting the servo pulse on the specified pin(s).
+  "
+  "
+  ``[<taskname>].lu9685,setrange,<startpin>,<startVarIndex>,<nrPins>``
+
+  startpin: 0 ... 19 or ``all``
+
+  startVarIndex: first index of a variable referring to 'N' similar to ``[int#N]``
+
+  nrPins: 1 ... 19
+  ","
+  **Set a range of pins to output a value as defined in variables.**
+
+  This command will copy the set values of a sequence of variables to a set range of pins.
+
+  If a referred variable was never set, the matching pin will be disabled.
+
+  This command will set all pins in a single I2C call, which limits communication overhead and also results in all pins being set at the same time.
+
+  .. note:: This will only update the pins when calling this command. It is not a continuous synchronisation between variables and pins.
+
+  For example:
+  ``lu9685,setrange,10,1000,2`` Will use the values stored in ``[int#1000]`` and ``[int#1001]`` to set pins ``10`` and ``11``.
+  "

docs/source/Plugin/_Plugin.rst

@@ -401,6 +401,7 @@ There are different released versions of ESP Easy:
    ":ref:`P173_page`","|P173_status|","P173"
    ":ref:`P175_page`","|P175_status|","P175"
    ":ref:`P176_page`","|P176_status|","P176"
+   ":ref:`P178_page`","|P178_status|","P178"
 
 
 .. include:: _plugin_sets_overview.repl
@@ -477,6 +478,8 @@ Extra IO
 
 Plugins: |Plugin_Extra_IO|
 
+Hardware: |P178_usedby|
+
 Gases
 -----
 

docs/source/Plugin/_plugin_categories.repl

@@ -9,7 +9,7 @@
 .. |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:`P105_page`, :ref:`P106_page`, :ref:`P122_page`, :ref:`P150_page`, :ref:`P151_page`, :ref:`P153_page`, :ref:`P154_page`, :ref:`P163_page`, :ref:`P167_page`, :ref:`P169_page`, :ref:`P172_page`, :ref:`P173_page`
-.. |Plugin_Extra_IO| replace:: :ref:`P011_page`, :ref:`P022_page`
+.. |Plugin_Extra_IO| replace:: :ref:`P011_page`, :ref:`P022_page`, :ref:`P178_page`
 .. |Plugin_Gases| replace:: :ref:`P049_page`, :ref:`P052_page`, :ref:`P083_page`, :ref:`P090_page`, :ref:`P117_page`, :ref:`P127_page`, :ref:`P135_page`, :ref:`P145_page`, :ref:`P147_page`, :ref:`P164_page`
 .. |Plugin_Generic| replace:: :ref:`P003_page`, :ref:`P026_page`, :ref:`P033_page`, :ref:`P037_page`, :ref:`P081_page`, :ref:`P100_page`, :ref:`P146_page`
 .. |Plugin_Gesture| replace:: :ref:`P064_page`