Merge pull request #2308 from Grovkillen/UpdateDocs

[docs] Adding P015 + some filters to rules + ThingSpeak info
2026-07-28 04:07:47 +00:00 · 2019-02-14 22:49:51 +01:00
parent 3d7f032ad1 391452246f
commit 77714d3105
17 changed files with 289 additions and 15 deletions
@@ -1,3 +1,3 @@
 recommonmark==0.4.0
-Sphinx==1.8.2
+Sphinx==1.8.4
 sphinx-bootstrap-theme==0.6.5
@@ -71,6 +71,7 @@ ThingSpeak only allows a message every 15 seconds for the free accounts.
 - **Max Queue Depth** - 1 (only report the last value)
 - **Max Retries** - 2
 - **Full Queue Action** - Delete Oldest
+- **Check Reply** - Check Acknowledgment (VERY IMPORTANT)
 - **Client Timeout** - 500 msec (server is online, so timeout must be a bit longer)


@@ -16,6 +16,12 @@

    ``IP,<IP address>``"
    "
+    Let","
+    :red:`Internal`","
+    Set the value of n (1..16).
+
+    ``Let,<n>,<value>``"
+    "
    LogEntry","
    :red:`Internal`","
    Add string to log
@@ -9,9 +9,9 @@

   .. code-block:: html

-      on DHT11Outside#Temperature>20 do
-       GPIO,2,1
-      endon
+        on DHT11Outside#Temperature>20 do
+         GPIO,2,1
+        endon

   "
   "
@@ -21,9 +21,9 @@

   .. code-block:: html

-      on System#Wake do
-        GPIO,15,1
-      endon
+        on System#Wake do
+          GPIO,15,1
+        endon

   "
   "
@@ -219,3 +219,27 @@
 	   endon

   "
+   "
+   ``GPIO#N``
+   If the command 'Monitor' is used to monitor a given pin you will receive an event for that GPIO as soon as it's state changes. As seen in the example you can always use the square brackets together with the task/value name of ``Plugin#GPIO#Pinstate#N`` to get the state, but to trigger events you need to add the monitor command (preferably at boot).
+   ","
+
+   .. code-block:: html
+
+       on System#Boot do
+        Monitor GPIO,15
+       endon
+
+        on GPIO#15=0 do
+         if [Plugin#GPIO#Pinstate#13]=0
+          // do something
+         endif
+        endon
+
+        on GPIO#15=1 do
+         if [Plugin#GPIO#Pinstate#13]=1
+          // do something
+         endif
+        endon
+
+   "
@@ -31,7 +31,7 @@ Supported hardware: |P000_usedby_GPIO|
  GPIO: 0 ... 16

  ","
-  **Toggle on/off.**. 
+  **Toggle on/off.**.
  Toggle the current (output) state of the given GPIO pin.
  This will only be executed on pins set to be in output mode.
  "
@@ -116,3 +116,19 @@ Supported hardware: |P000_usedby_GPIO|
  A position value of 9000 will stop the PWM signal.
  This can be useful to save energy on servos which do not need power to remain at the same position.
  "
+  "
+  ``Monitor,<GPIO>``
+
+  GPIO: 0 ... 16
+  ","
+  **To monitor a GPIO state.**
+  By the use of the command you will receive events when the GPIO state of that pin is changed from 1 to 0 and from 0 to 1.
+  "
+  "
+  ``GPIOtoggle,<GPIO>``
+
+  GPIO: 0 ... 16
+  ","
+  **To toggle a GPIO state.**
+  With this command you can change the given state of a pin from either 1 to 0 or from 0 to 1.
+  "
@@ -0,0 +1,129 @@
+.. include:: ../Plugin/_plugin_substitutions_p01x.repl
+.. _P015_TSL2561_page:
+
+TSL2561
+=======
+
+|P015_typename|
+|P015_status|
+
+.. image:: P015_TSL2561_1.jpg
+
+Introduction
+------------
+The TSL2561 are light-to-digital converters that transform light intensity to a digital
+signal output. First targeted to accompany LCD and OLED displays in order to dim them
+if the ambient light is lower, making the battery life better for the unit its a part of.
+The unit can also be found in illuminated keyboards and digital cameras.
+
+The TSL2561 sensor is a luminosity sensor. It's spectral sensitivity approximately meets
+the human eye sensitivity. The gain of the sensor can be set to a 16x gain mode with the settings.
+It is connected to the ESP via I²C so connecting even with several sensors and a display is easy to do.
+
+Specifications:
+ * Output: 0.1 - 40 000+ Lux
+ * Temperature (-30 to +70C but best readings between +5 to +50C)
+ * Humidity (0 - 60 % rel. humidity)
+
+
+Wiring
+------
+
+.. image:: P015_TSL2561_2.jpg
+
+.. code-block:: html
+
+  ESP               TSL2561
+  GPIO (5)   <-->   SCL
+  GPIO (4)   <-->   SDA
+                    ADDR (not used = 0x39)
+
+  Power
+  3.3V       <-->   VCC
+  GND        <-->   GND
+
+The ADDR pin can be used if you have an i2c address conflict, to change the address.
+
+Connect it to GND to set the address to 0x29.
+
+Connect it to VCC (3.3V) to set the address to 0x49.
+
+Leave it floating (unconnected) to use address 0x39.
+
+Some boards have soldering pads or jumper selectors for the ADDR.
+
+.. image:: P015_TSL2561_wiring_1.jpg
+
+Setup
+-----
+
+.. image:: P015_Setup_TSL2561_1.png
+
+Task settings
+~~~~~~~~~~~~~
+
+* **Device**: Name of plugin
+* **Name**: Name of the task (example name **Light**)
+* **Enable**: Should the task be enabled or not
+
+Sensor
+^^^^^^
+
+* **I2C Address**: Default 0x39 is used.
+* **Integration time**: 13 msec is the default, works in normal lit areas. Increase the integration time for low light areas, it will collect light longer if set to longer time.
+* **Send sensor to sleep**: Have it checked in order to save the unit from wear, especially good if you do measurements with long intervals in between.
+* **Enable 16x Gain**: Have it checked in order to get higher readings in low light areas.
+
+Data acquisition
+^^^^^^^^^^^^^^^^
+
+* **Send to controller** 1..3: Check which controller (if any) you want to publish to. All or no controller can be used.
+* **Interval**: How often should the task publish its value (5..15 seconds is normal).
+
+Indicators (recommended settings)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. csv-table::
+  :header: "Indicator", "Value Name", "Interval", "Decimals", "Extra information"
+  :widths: 8, 5, 5, 5, 40
+
+  "Visible light", "VI_Lux", "10", "0", "In normal lit areas you probably don't need a decimal."
+  "Infrared light", "IR_Lux", "10", "0", "Light not visible to humans but felt in some cases, used in dry saunas and patio heating etc."
+  "Broadband light", "BR_Lux", "10", "0", "Visible or near visible light that is felt, used in skin treatments etc."
+
+Rules examples
+--------------
+
+.. code-block:: html
+
+    on Light#VI_Lux do
+     if Light#VI_Lux>100
+       Publish,%sysname%/light,Is on
+     else
+       Publish,%sysname%/light,Is off
+     endif
+    endon
+
+.. Commands available
+.. ~~~~~~~~~~~~~~~~~~
+
+.. .. include:: P015_commands.repl
+
+Where to buy
+------------
+
+.. csv-table::
+ :header: "Store", "Link"
+ :widths: 5, 40
+
+ "AliExpress","`Link 1 ($) <http://s.click.aliexpress.com/e/1Cehi80>`_"
+ "Banggood","`Link 2 ($) <https://www.banggood.com/custlink/33GDYjRHyC>`_"
+ "eBay","`Link 3 ($) <https://rover.ebay.com/rover/1/711-53200-19255-0/1?icep_id=114&ipn=icep&toolid=20004&campid=5338336929&mpre=https%3A%2F%2Fwww.ebay.com%2Fsch%2Fi.html%3F_from%3DR40%26_trksid%3Dm570.l1313%26_nkw%3Dtsl2561%26_sacat%3D0>`_"
+
+|affiliate|
+
+
+.. More pictures
+.. -------------
+
+.. .. image:: P015_TSL2561_X.jpg
@@ -53,6 +53,11 @@ Setup

 .. image:: P082_Setup_Neo-6M_1.png

+A screenshot of a later relase of the plugin. The use of hardware serial communication
+makes the transfer between the GPS and ESP a LOT more stable:
+
+.. image:: P082_Setup_1.png
+
 Task settings
 ~~~~~~~~~~~~~

@@ -54,6 +54,11 @@ Setup

 .. image:: P082_Setup_Neo-7M_1.png

+A screenshot of a later relase of the plugin. The use of hardware serial communication
+makes the transfer between the GPS and ESP a LOT more stable:
+
+.. image:: P082_Setup_1.png
+
 Task settings
 ~~~~~~~~~~~~~

@@ -67,8 +72,8 @@ Sensor
 * **GPIO <-- TX**: Used to communicate with the GPS unit.
 * **GPIO --> RX**: Not used (optional), to push commands back into the GPS unit.
 * **GPIO --> PPS**: Experimental (optional), used to let the GPS unit update the time of the ESP.
-* **Dropdown**: ``SoftwareSerial`` lets you select any GPIO pin, ``HW Serial0`` is the preferred (most stable), ``HW Serial0 swapped`` is similar to Serial0, ``HW Serial1`` is only able
-to receive data from the GPS unit.
+* **Dropdown**: ``SoftwareSerial`` lets you select any GPIO pin, ``HW Serial0`` is the preferred (most stable),
+                ``HW Serial0 swapped`` is similar to Serial0, ``HW Serial1`` is only able to receive data from the GPS unit.

 .. warning:: It's highly recommended you use either the ``HW Serial1`` or ``HW Serial0`` for stable reading of the GPS unit. But also remember to disable the serial in the
             advanced settings page, if not the ESP will interfere with the GPS unit.
@@ -56,6 +56,11 @@ Setup

 .. image:: P082_Setup_Neo-M8n_1.png

+A screenshot of a later relase of the plugin. The use of hardware serial communication
+makes the transfer between the GPS and ESP a LOT more stable:
+
+.. image:: P082_Setup_1.png
+
 Task settings
 ~~~~~~~~~~~~~

@@ -69,8 +74,8 @@ Sensor
 * **GPIO <-- TX**: Used to communicate with the GPS unit.
 * **GPIO --> RX**: Not used (optional), to push commands back into the GPS unit.
 * **GPIO --> PPS**: Experimental (optional), used to let the GPS unit update the time of the ESP.
-* **Dropdown**: ``SoftwareSerial`` lets you select any GPIO pin, ``HW Serial0`` is the preferred (most stable), ``HW Serial0 swapped`` is similar to Serial0, ``HW Serial1`` is only able
-to receive data from the GPS unit.
+* **Dropdown**: ``SoftwareSerial`` lets you select any GPIO pin, ``HW Serial0`` is the preferred (most stable),
+                ``HW Serial0 swapped`` is similar to Serial0, ``HW Serial1`` is only able to receive data from the GPS unit.

 .. warning:: It's highly recommended you use either the ``HW Serial1`` or ``HW Serial0`` for stable reading of the GPS unit. But also remember to disable the serial in the
             advanced settings page, if not the ESP will interfere with the GPS unit.
@@ -127,7 +132,7 @@ Where to buy

  "AliExpress","`Link 1 ($) <http://s.click.aliexpress.com/e/cmauSCgs>`_"
  "Banggood","`Link 2 ($) <https://www.banggood.com/custlink/G3vvYRCdgh>`_ `Link 3 ($) <https://www.banggood.com/custlink/mmvmdYpEBr>`_"
-  "eBay","`Link 3 ($) <https://rover.ebay.com/rover/1/711-53200-19255-0/1?icep_id=114&ipn=icep&toolid=20004&campid=5338336929&mpre=https%3A%2F%2Fwww.ebay.com%2Fsch%2Fi.html%3F_nkw%3Dneo%2520m8n>`_"
+  "eBay","`Link 4 ($) <https://rover.ebay.com/rover/1/711-53200-19255-0/1?icep_id=114&ipn=icep&toolid=20004&campid=5338336929&mpre=https%3A%2F%2Fwww.ebay.com%2Fsch%2Fi.html%3F_nkw%3Dneo%2520m8n>`_"

 |affiliate|

@@ -204,6 +204,8 @@ Light/Lux

 Plugins: |Plugin_Light_Lux|

+Hardware: |P015_usedby|
+
 Motor
 -----

@@ -64,8 +64,8 @@
 .. |P015_status| replace:: :green:`NORMAL`
 .. |P015_github| replace:: P015_TSL2561.ino
 .. _P015_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P015_TSL2561.ino
-.. |P015_usedby| replace:: `.`
-.. |P015_shortinfo| replace:: `.`
+.. |P015_usedby| replace:: :ref:`P015_TSL2561_page`
+.. |P015_shortinfo| replace:: Light measuring unit (visible and IR light)
 .. |P015_maintainer| replace:: `.`
 .. |P015_compileinfo| replace:: `.`
 .. |P015_usedlibraries| replace:: `.`
@@ -256,6 +256,19 @@ the code more readable:
 [DeviceName#ValueName]<<value> //These work...
 [DeviceName#ValueName] < <value> //the same...

+Special task names
+------------------
+
+You must not use the task name ``VAR`` as this is used for the internal
+variables. The variables set with the ``Let`` command will be available in rules
+as ``VAR#N`` where ``N`` is 1..16.
+
+Clock, Rules and System etc. are not recommended either since they are used in
+event names.
+
+Please observe that task names are case insensitive meaning that VAR, var, and Var etc.
+are all treated the same.
+
 Some working examples
 =====================

@@ -342,6 +355,74 @@ You could then use the command "ToggleGPIO" with dynamic GPIO numbers and state.

 http://<espeasyip>/control?cmd=event,ToggleGPIO=12,1

+Internal variables
+------------------
+
+A really great feature to use is the 16 internal variables. You set them like this:
+
+.. code-block:: html
+
+ Let,<n>,<value>
+
+Where n can be 1 to 16 and the value an float. To use the values in strings you can
+either use the ``%v7%`` syntax or ``[VAR#7]``. BUT for formulas you need to use the square
+brackets in order for it to compute, i.e. ``[VAR#12]``.
+
+
+Averaging filters
+-----------------
+
+You may want to clear peaks in otherwise jumpy measurements and if you cannot
+remove the jumpiness with hardware you might want to add a filter in the software.
+
+A **10 value average**:
+
+.. code-block:: html
+
+  On Temp#Value Do
+   Let,10,[VAR#9]
+   Let,9,[VAR#8]
+   Let,8,[VAR#7]
+   Let,7,[VAR#6]
+   Let,6,[VAR#5]
+   Let,5,[VAR#4]
+   Let,4,[VAR#3]
+   Let,3,[VAR#2]
+   Let,2,[VAR#1]
+   Let,1,[Temp#Value]
+   TaskValueSet,12,1,([VAR#1]+[VAR#2]+[VAR#3]+[VAR#4]+[VAR#5]+[VAR#6]+[VAR#7]+[VAR#8]+[VAR#9]+[VAR#10])/10
+  EndOn
+
+In the above example we use the sensor value of ``Temp#Value`` to get the trigger event,
+we then add all the previous 9 values to the internal variables and the newly acquired
+value to the first variable. We then summarize them and divide them by 10 and store it
+as a dummy variable (example is on task 12, value 1) which we use to publish the sliding
+value instead of the sensor value.
+
+Another filter could be to just use the previous value and **dilute** the new value with that one:
+
+.. code-block:: html
+
+  On Temp#Value Do
+    Let,2,[VAR#1]
+    Let,1,[Temp#Value]
+    TaskValueSet,12,1,(3*[VAR#1]+[VAR#2])/4
+  EndOn
+
+
+Yet another filter could be to add the new value to a **summarized average**:
+
+.. code-block:: html
+
+  On Temp#Value Do
+    Let,1,[Temp#Value]
+    TaskValueSet,12,1,([VAR#1]+3*[VAR#2])/4
+    Let,2,[Dummy#Value]
+  EndOn
+
+What you should use? That is a case by case question. Try them all and see which
+one suits your actual scenario the best.
+
 PIR and LDR
 -----------