Michel2/ESPEasy
1
0
Fork 0
mirror of https://github.com/letscontrolit/ESPEasy.git synced 2026-09-15 02:54:26 +00:00
Code Issues Releases Activity

Merge branch 'mega' into feature/MQTT_TLS

Browse Source
This commit is contained in:
TD-er
2024-07-13 12:45:11 +02:00
parent 4f4ff8721b c44c85c907
commit 8b992eb352
998 changed files with 136191 additions and 89948 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/Controller/_controller_substitutions.repl
+1 -1
View File
@@ -114,7 +114,7 @@
.. |C011_name| replace:: :cyan:`Generic HTTP Advanced`
.. |C011_type| replace:: :cyan:`Controller`
.. |C011_typename| replace:: :cyan:`Controller - Generic HTTP Advanced`
.. |C011_status| replace:: :yellow:`COLLECTION`
.. |C011_status| replace:: :yellow:`COLLECTION` :yellow:`CLIMATE`
.. |C011_github| replace:: C011.cpp
.. _C011_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C011.cpp
.. |C011_usedby| replace:: `.`
docs/source/ESPEasy/ESPchips.rst
+15 -13
View File
@@ -10,8 +10,8 @@ ESPEasy does support a number of variants of the processors manufactured by Espr
* **ESP32-S2** Has more GPIO pins than the ESP32, but only 1 CPU core. Initial support in ESPEasy added since 2021-09-19.
* **ESP32-S3** Support added: 2023-05-03
* **ESP32-C3 / ESP8685** Support added: 2023-05-03
* **ESP32-C2 / ESP8684** Not yet supported
* **ESP32-C6** Not yet supported
* **ESP32-C2 / ESP8684** Support added: 2023-11-10
* **ESP32-C6** Support added: 2023-11-10
* **ESP32-H2** Not yet supported
@@ -83,7 +83,7 @@ ESPEasy does support a number of variants of the processors manufactured by Espr
- 2022
- 2021
- 2021
* - Status (2023/05)
* - Status (2024/03)
- NRND
- Mass Production (solo1: NRND)
- NRND
@@ -91,7 +91,7 @@ ESPEasy does support a number of variants of the processors manufactured by Espr
- Mass Production
- Mass Production
- Mass Production
- Sample
- Mass Production
* - Wi-Fi
- IEEE 802.11 b/g/n; 2.4 GHz; HT20; up to 72 Mbps
- IEEE 802.11 b/g/n; 2.4 GHz; HT20/40; up to 150 Mbps
@@ -328,12 +328,12 @@ ESPEasy does support a number of variants of the processors manufactured by Espr
- 0
* - Ethernet
- 0
- 1 (RMII)
- 0
- 0
- 0
- 0
- 0
- 1 (RMII and SPI)
- 1 (SPI)
- 1 (SPI)
- 1 (SPI)
- 1 (SPI)
- 1 (SPI)
- 0
* - TWAI (CAN)
- 0
@@ -651,6 +651,8 @@ To support all modes, we simply need to make several versions
- 2 MB (Quad SPI)
- ``qio_qspi``
`Table Source <https://api.riot-os.org/group__cpu__esp32__esp32s3.html>`_
Build versions:
@@ -681,7 +683,7 @@ ESP32-C2/ESP8684
Added: 2023/11/10
The ESP32-C2 is only available with embedded flash and can only be found labelled as "ESP8684".
The ESP32-C2 is only available with embedded flash and can also be found labeled as "ESP8684".
It looks like it is aimed to be used in single purpose devices, due to its low GPIO count and only requiring a bare minimum of external parts.
@@ -698,9 +700,9 @@ Added: 2023/11/10
The ESP32-C6 seems to be aimed at being used as a gateway for the new Thread protocol and Wi-Fi.
It is the more powerful version of the ESP32-H2 and also includes not only the traditional 2.4 GHz Wi-Fi, but also the new Wi-Fi6 standard on 2.4 GHz.
It is the more powerful version of the ESP32-H2 and also includes not only the traditional 2.4 GHz Wi-Fi, but also the new Wi-Fi6 standard on 2.4 GHz and IEEE 802.15.4 (Zigbee/Thread). Zigbee/Thread not yet supported by ESPEasy (March 2024).
.. note:: Labelled as "unstable" by the Arduino team (as of Nov 2023), preliminary support in ESPEasy
.. note:: Labeled as "unstable" by the Arduino team (as of Nov 2023), preliminary support in ESPEasy
ESP32-H2
========
docs/source/Hardware/Hardware.rst
+94 -13
View File
@@ -3,8 +3,6 @@
Hardware page
*************
Overview
========
ESPEasy has some centralized hardware configuration settings, shown in this page, and divided in sections.
@@ -55,6 +53,9 @@ ESPEasy has a separate setting for Slow I2C devices, and per I2C device this slo
.. image:: Device_I2COptionsShort.png
Added: 2023-11-23
A device flag has been added for specific devices to have **Force Slow I2C speed** set by default. After adding the device this option will be checked, but can still be unchecked to use (try) Fast I2C speed (400 kHz).
---------------
I2C Multiplexer
@@ -200,13 +201,34 @@ To activate a new configuration, a reboot is needed.
Ethernet PHY type
^^^^^^^^^^^^^^^^^
Select the used PHY controller type:
ESP boards can be equiped with Ethernet.
This is more stable and reliable compared to WiFi and allows for better responsiveness.
* LAN8710 (LAN8720 is also supported, but none of the newer features are supported)
* TLK110
* RTL8201 (since ESP32 IDF 4.4)
* DP83848 (since ESP32 IDF 4.4)
* DM9051 (since ESP32 IDF 4.4)
Actual transfer speed (at least when using RMII) is also higher than can be achieved via WiFi, but this is less of a concern for typical use cases where ESPEasy is used.
Ethernet chips/boards for ESP32-variant boards exist with 2 types of interfaces to the ESP.
* RMII interface - Faster actual transfer speeds possible, uses more GPIO pins, only supported on ESP32-classic (and upcoming ESP32-P4).
* SPI interface - (Added: 2024/02) Supported on all ESP32-variants (not all tested) on builds based on ESP-IDF 5.1
SPI Ethernet adapters do obviously require the SPI interface to be configured.
N.B. Only ESP32-variant builds with LittleFS support SPI Ethernet. (starting February 2024)
Supported Ethernet chips:
* RMII Interface:
* LAN8710 (LAN8720 is also supported, but none of the newer features are supported)
* TLK110
* RTL8201 (since ESP32 IDF 4.4)
* JL1101 (since ESP32 IDF 4.4)
* DP83848 (since ESP32 IDF 4.4)
* KSZ8041 (since ESP32 IDF 4.4)
* KSZ8081 (since ESP32 IDF 4.4)
* SPI Interface: (since ESP32 IDF 5.1)
* DM9051
* W5500
* KSZ8851
.. note:: The LAN8710 and LAN8720 are also available with an "A" suffix.
These are the same chips, only produced after the brand SMSC was taken over by Microchip Technology.
@@ -216,19 +238,22 @@ Ethernet PHY Address
The PHY address depends on the hardware and the PHY configuration.
On some chips, like the LAN8720, the board designer may set this address by pulling some pins either high or low at power on.
In theory, one could use multiple PHY adapters on the same RMII bus, but this is not supported by ESPEasy.
In theory, one could use multiple PHY adapters on the same RMII/SPI bus, but this is (currently) not supported by ESPEasy.
* Espressif's Ethernet board with TLK110 PHY use PHY address 31.
* Common Waveshare LAN8720 PHY breakout board (and clones) use PHY address 1.
* Olimex ESP32 EVB REV B IoT LAN8710 PHY Board with CAN use PHY address 0.
* Other LAN8720 breakouts often use PHY address 0.
* ETH01-EVO (ESP32-C3 based board) uses PHY address 1.
If the PHY address is incorrect then the EMAC will initialise but all attempts to read/write configuration registers on the PHY will fail.
N.B. There is support for an auto detect of this PHY address, by setting it to -1, but at least on the LAN8720 this does not seem to work.
GPIO pins
^^^^^^^^^
RMII Ethernet
^^^^^^^^^^^^^
As mentioned above, the RMII interface is only present on ESP32-classic (and is mentioned on the announced ESP32-P4).
RMII PHY SMI Wiring
"""""""""""""""""""
@@ -278,7 +303,43 @@ Apart from these GPIO pins, there is a number of other pins reserved on the ESP3
Since these GPIO pin assignments cannot be changed, it is also not needed to configure them.
However, they also cannot be used when *RMII PHY* is used.
.. include:: ../Reference/Ethernet_PHY_ESP32.rst
.. include:: ../Reference/RMII_Ethernet_PHY_ESP32.rst
RMII Ethernet ESP32 Boards
""""""""""""""""""""""""""
.. include:: ../Reference/RMII_Ethernet_ESP32_boards.rst
SPI Ethernet
^^^^^^^^^^^^
(Added: 2024/02)
As mentioned above, these SPI based Ethernet interfaces require the SPI interface to be configured.
The SPI bus can be shared, but the SPI Ethernet chips are a bit specific about the used frequency.
Currently the default SPI frequency of 20 MHz is used, so not all other SPI devices may work together with SPI Ethernet.
Some boards like the ETH01-EVO (ESP32-C3 based) do not even have the SPI bus pins made accesible.
.. note:: Switching to ECO mode can sometimes result in an unreachable node when using SPI Ethernet. After a reboot the node works just fine again (in ECO mode). This is currently being investigated.
GPIO Configuration
""""""""""""""""""
* CS pin: Just as any SPI device, it needs a CS pin to tell the device it is being addressed.
* IRQ/INT pin: Allows the Ethernet chip to signal the ESP about new data. (Optional for W5500)
* RST pin: ESP will try to reset the Ethernet adapter during boot. Not all boards may have this wired.
SPI Ethernet ESP32 Boards
"""""""""""""""""""""""""
.. include:: ../Reference/SPI_Ethernet_ESP32_boards.rst
Ethernet with PoE
^^^^^^^^^^^^^^^^^
@@ -288,13 +349,33 @@ Some ethernet boards support Power over Ethernet (PoE), so only a single (ethern
For Olimex boards in the ESP32-POE range, the supplier has documented this warning:
.. warning::
**Important notice**: Olimex ESP32-PoE has **no galvano isolation** from Ethernet's power supply, when you program the board via the micro USB connector the Ethernet cable should be disconnected (if you have power over the Ethernet cable)!
**Important notice**: Olimex ESP32-PoE has **no galvanic isolation** from Ethernet's power supply, when you program the board via the micro USB connector the Ethernet cable should be disconnected (if you have power over the Ethernet cable)!
Consider using Olimex USB-ISO to protect your computer and board from accidental short circuit. Also consider instead using Olimex ESP32-PoE-ISO board, which *is* insulated.
Most likely, this warning is applicable to other brands as well.
Ethernet Isolation
^^^^^^^^^^^^^^^^^^
Most Ethernet RJ45 phy (the connector on the PCB) have isolation transformers in them.
This does isolate the TX/RX pins to make sure there is no direct connection between the long cables and the Ethernet controller chip.
The isolation does protect the Ethernet chip from picked up high voltage spikes and ESD surges when inserting the Ethernet cable.
However not all ESP boards with Ethernet have these installed.
Apart from the isolation of the TX/RX pins the metallic enclosure of the phy should also be isolated from the rest of the circuit of the ESP board.
Typically this is done by connecting the metal enclosure of the phy via a capacitor to GND of the rest of the circuit.
A lot of boards with Ethernet have these directly connected to GND, which may impose a problem when connecting the ESP board to your PC.
.. warning::
**Important notice**: For ESP boards with Ethernet which need debugging, never use Ethernet cables with metal shielding on the Ethernet connector.
Using shielded Ethernet cable will connect the metal shield of the RJ45 phy to the ground of the switch and this may be connected to other appliances which may be badly grounded.
This will add a significant voltage offset between the ESP board and your PC while debugging.
Such a high voltage is very likely to destroy electronics.
-------------------
GPIO boot states
-------------------
docs/source/Participate/ProjectStructure.rst
+27 -20
View File
@@ -29,7 +29,7 @@ Below a list of the most important directories and files used in this project.
* ``platformio.ini`` Configuration file for PlatformIO to define various build setups.
* ``uncrustify.cfg`` Configuration file for Uncrustify, to format source code using some uniform formatting rules.
* ``requirements.txt`` List of used Python libraries and their version (result of ``pip freeze`` with Virtual env active)
* ``esp32_partition_app1810k_spiffs316k.csv`` Used partition layout in ESP32 builds.
* ``boards/partitions/esp32_partition_app1810k_spiffs316k.csv`` Used partition layout in ESP32 4M builds.
ESPEasy src dir
@@ -90,11 +90,11 @@ The filename is quite descriptive:
Build Type
----------
Build type can be: (differ in included plugins)
Build type can be: (differences in included plugins)
* normal => Only Stable plugins and controllers
* test => Stable + Testing (split into multiple sets, A/B/C/D)
* max => All available plugins
* normal => Only Stable plugins and controllers
* collection => Stable + Collection (split into multiple sets, A/B/C/D/E/F/G)
* max => All available plugins and features
There is also a number of special builds:
@@ -111,8 +111,10 @@ ESP Chip Type
* ``ESP8285`` Supported in ``ESP8266`` builds. Used in some Sonoff modules. This chip has embedded flash, so no extra flash chip.
* ``ESP32`` Allows for more memory and more GPIO pins.
* ``ESP32-S2`` Newer version of ESP32. Has even more GPIO pins, but some specific features of ESP32 were removed.
* ``ESP32-S3`` Not yet available.
* ``ESP32-C3`` Support will be added soon.
* ``ESP32-S3`` Newer version of ESP32 and ESP32-S2. Has even more GPIO pins, some specific features of ESP32 were removed, and some design choices of ESP32-S2 are reverted and implemented differently.
* ``ESP32-C2`` Preliminary supported. Cheaper variant of ESP32-C3, and also an ESP8266 replacement. Available as pin-compatible module for ESP8266. Single core, and max 120 MHz clock speed.
* ``ESP32-C3`` Intended as a replacement for ESP8266, using ESP32 technology, though single-core and with limited clock speed (160 MHz, some models 120 MHz).
* ``ESP32-C6`` Preliminary supported. Will allow connectivity with IEEE 802.15.4 (Thread/Zigbee) wireless protocol.
Memory Size and Partitioning
----------------------------
@@ -124,23 +126,27 @@ Memory Size and Partitioning
* ``4M1M`` 4 MB flash modules with 1 MB filesystem (usually SPIFFS)
* ``4M2M`` 4 MB flash modules with 2 MB filesystem (usually SPIFFS)
* ``4M316k`` 4 MB flash modules using 1.8 MB sketch size, with 316 kB filesystem (usually SPIFFS) (for ESP32)
* ``8M1M`` 8 MB flash modules using 3.5MB sketch size, with 1 MB filesystem (LittleFS) (ESP32 only a.t.m.)
* ``16M1M`` 16 MB flash modules using 4MB sketch size, with 1 MB filesystem (usually SPIFFS) (ESP32 only a.t.m.)
* ``16M2M`` 16 MB flash modules using 4MB sketch size, with 2 MB filesystem (LittleFS) (ESP32 only a.t.m.)
* ``16M8M`` 16 MB flash modules using 4MB sketch size, with 8 MB filesystem (LittleFS) (ESP32 only a.t.m.)
Optional build options
----------------------
* ``LittleFS`` Use LittleFS instead of SPIFFS filesystem (SPIFFS is unstable > 2 MB)
* ``LittleFS`` Use LittleFS instead of SPIFFS filesystem (SPIFFS is unstable \> 2 MB and no longer available from IDF 5.x)
* ``VCC`` Analog input configured to measure VCC voltage
* ``OTA`` Arduino OTA (Over The Air) update feature enabled
* ``Domoticz`` Only Domoticz controllers (HTTP+MQTT) and plugins included
* ``FHEM_HA`` Only FHEM/OpenHAB/Home Assistant (MQTT) controllers and plugins included
* ``lolin_d32_pro`` Specific Lolin hardware options enabled
* ``PSRAM`` Additional PSRAM support (ESP32 only)
* ``OPI`` Flash via OPI protocol support (ESP32 only)
* ``QIO`` Flash via QIO protocol support (ESP32 only)
* ``CDC`` CDC Serial (built-in USB) support (ESP32 only)
* ``ETH`` Ethernet interface enabled (ESP32 only)
Please note that the performance of 14MB SPIFFS (16M flash modules) is really slow.
Please note that the performance of 14MB SPIFFS (16M flash ESP8266 modules) is really slow.
All file access takes a lot longer and since the settings are also read from flash, the entire node will perform slower.
See `Arduino issue - SPIFFS file access slow on 16/14M flash config <https://github.com/esp8266/Arduino/issues/5932>`_
@@ -150,7 +156,7 @@ Special memory partitioning:
* ``2M256`` 2 MB flash modules (e.g. Shelly1/WROOM02) with 256k SPIFFS (only core 2.5.0 or newer)
* ``4M316k`` For ESP32 with 4MB flash, sketch size is set to 1.8 MByte (default: 1.4 MByte)
* ``4M1M`` 4MB flash, 1 MB SPIFFS. Default layout for 4MB flash.
* ``4M1M`` 4MB flash, 1 MB SPIFFS. Default layout for ESP8266 4MB flash.
* ``4M2M`` 4MB flash, 2 MB SPIFFS. Introduced in October 2019. Only possible with core 2.5.2 or newer.
.. warning::
@@ -165,7 +171,7 @@ Difference between .bin and .bin.gz
Starting on esp8266/Arduino core 2.7.0, it is possible to flash images that have been compressed using GZip.
Please note that this only can be used on installs already running a very recent build.
Please note that this only can be used on installs already running a recent build.
This also means we still need to update the 2-step updater to support .bin.gz files.
@@ -182,17 +188,17 @@ There are several builds for ESP32:
* ``normal_ESP32_4M316k`` Build using the "stable" set of plugins for ESP32
* ``normal_ESP32_4M316k_ETH`` Build using the "stable" set of plugins for ESP32, with support for an on-board Ethernet controller
* ``custom_ESP32_4M316k`` Build template using either the plugin set defined in ``Custom.h`` or ``tools/pio/pre_custom_esp32.py``
* ``test_A_ESP32_4M316k`` Build using the "testing" set "A" of plugins for ESP32
* ``test_B_ESP32_4M316k`` Build using the "testing" set "B" of plugins for ESP32
* ``test_C_ESP32_4M316k`` Build using the "testing" set "C" of plugins for ESP32
* ``test_D_ESP32_4M316k`` Build using the "testing" set "D" of plugins for ESP32
* ``test_A_ESP32-wrover-kit_4M316k`` A build for ESP32 including build flags for the official WRover test kit.
* ``collection_A_ESP32_4M316k`` Build using the "Collection" set "A" of plugins for ESP32
* ``collection_B_ESP32_4M316k`` Build using the "Collection" set "B" of plugins for ESP32
* ``collection_C_ESP32_4M316k`` Build using the "Collection" set "C" of plugins for ESP32
* ``collection_D_ESP32_4M316k`` Build using the "Collection" set "D" of plugins for ESP32
* ``collection_A_ESP32-wrover-kit_4M316k`` A build for ESP32 including build flags for the official WRover test kit.
* ``max_ESP32_16M8M_LittleFS`` Build using all available plugins and controllers for ESP32 with 16 MB flash (some lolin_d32_pro boards)
Since ESP32 does have its flash partitioned in several blocks, we have 2 bin files of each ESP32 build, f.e.:
* ``test_D_ESP32_4M316k.bin`` Use for OTA upgrades.
* ``test_D_ESP32_4M316k.factory.bin`` Use on clean nodes as initial inistall.
* ``collection_D_ESP32_4M316k.bin`` Use for OTA upgrades.
* ``collection_D_ESP32_4M316k.factory.bin`` Use on clean nodes as initial inistall.
The binary with ``.factory`` in the name must be flashed on a new node, via the serial interface of the board.
This flash must be started at address 0.
@@ -208,7 +214,8 @@ To help recover from a bad flash, there are also blank images included.
* ``blank_1MB.bin``
* ``blank_2MB.bin``
* ``blank_4MB.bin``
* ``blank_8MB.bin``
* ``blank_16MB.bin``
When the wrong image is flashed, or the module behaves unstable, or is in a reboot loop,
flash these images first and then the right image for the module.
flash these images first to clear out any remaining or hidden settings (Arduino framework...) and then the right image for the module.
docs/source/Plugin/AdaGFX_commands.repl
+9 -2
View File
@@ -81,7 +81,7 @@
Some display types may limit or extend the maximum accepted size.
"
"
``<trigger>,txtfull,<x>,<y>,<size=1>,<foreColor=current>,<backColor=foreColor>, <textPrintMode=current>,<maxTextWidthPixels=0>,<text>``
``<trigger>,txtfull,<x>,<y>,<size=1>,<foreColor=current>,<backColor=foreColor>,`` ``<textPrintMode=current>,<maxTextWidthPixels=0>,<text>``
","
Write text at position X/Y with all options. Depending on the setting **Text Coordinates in col/row**, these coordinates are pixels (default) or column/rows.
@@ -116,6 +116,7 @@
* *sevenseg24* A rather large 7-segment 21 * 48 font
* *sevenseg18* A somewhat less large 7-segment 16 * 34 font
* *freesans* A sans-serif 10 * 21 font
* *tomthumb* A small 3 * 5 font, for use on a 5x29 NeoPixel display. Not available in limited builds.
Usually disabled fonts: (can be enabled in a Custom build, default enabled in the MAX builds)
@@ -136,7 +137,11 @@
* *whiterabbit16pt* A modern 16 * 20 font
* *robotomono16pt* A modern 16 * 20 font
* *whiterabbit18pt* A modern 18 * 22 font
* *sevenseg18b* A better 18 * 22 font, where the 1 isn't proportionally spaced, but doesn't have much non-alphanumeric characters
* *lcd14cond18pt* A 14 segment, 18pt, LCD-like font
* *whiterabbit20pt* A modern 20 * 24 font
* *sevenseg24b* A better 24 * 34 font, where the 1 isn't proportionally spaced, but doesn't have much non-alphanumeric characters
* *lcd14cond24pt* A 14 segment, 24pt, LCD-like font
Standard disabled fonts (even on MAX builds), that can be enabled in a custom build:
@@ -148,6 +153,8 @@
* *robotocond16pt* A modern 16 * 20 font (Roboto Condensed, proportionally spaced)
NB: Roboto is used as the default Android font since Android 4.1, and very readable, even when using small fonts on a small display.
NB2: The 18pt fonts are included by default in the ESP32 builds, using this helper.
"
"
``<trigger>,l,<x1>,<y1>,<x2>,<y2>,<color>``
@@ -252,7 +259,7 @@
The file will be read from SD-card, when available, and the bmp file is not found on the internal file storage.
"
"
``<trigger>,btn,<state>,<mode>,<x>,<y>,<w>,<h>,<id>,<type>,<ONcolor=blue>,<OFFcolor=red>, <CaptionColor=white>,<fontsize>,<ONcaption>,<OFFcaption>,<BorderColor=white>, <DisabledColor=0x9410>,<DisabledCaptionColor=0x5A69>,<TaskIndex>,<Group>, <SelectGroup>,<objectname>``
``<trigger>,btn,<state>,<mode>,<x>,<y>,<w>,<h>,<id>,<type>,<ONcolor=blue>,<OFFcolor=red>,`` ``<CaptionColor=white>,<fontsize>,<ONcaption>,<OFFcaption>,<BorderColor=white>,`` ``<DisabledColor=0x9410>,<DisabledCaptionColor=0x5A69>,<TaskIndex>,<Group>,`` ``<SelectGroup>,<objectname>``
","
As a companion to the ESPEasy_TouchHelper, the AdafruitGFX_helper takes care of drawing button objects via this subcommand.
docs/source/Plugin/AdaGFX_values.repl
+94 -94
View File
@@ -1,94 +1,94 @@
.. csv-table::
:escape: ^
:widths: 20, 30
"
Generic variables, available for all ``AdafruitGFX_Helper`` enabled plugins, currently: :ref:`P095_page`, :ref:`P096_page`, :ref:`P116_page`, :ref:`P131_page` and :ref:`P141_page`.
","
Generic notes:
* If an argument has comma's or spaces, then that part should be 'wrapped' in either double quotes ``^"``, single quotes ``^'`` or back-ticks ``^```.
* The ``<taskname>`` part is the name of the Device task.
* True(1)/False(0) values can optionally return -1 to indicate an invalid request, like a missing Window Id.
* All sizes, lengths etc. are returned in pixels.
"
"
``[<taskname>#win]``
","
Get the currently active Window Id, expected range: 0..255.
"
"
``[<taskname>#iswin,<windowId>]``
","
Is the request Window Id valid, expected result: 1 = true, 0 = false.
"
"
``[<taskname>#width]``
","
Get the width of the currently active Window and rotation, expected range 0..<largest display dimension>.
"
"
``[<taskname>#height]``
","
Get the height of the currently active Window and rotation, expected range 0..<largest display dimension>.
"
"
``[<taskname>#length,^"<text to measure>^"]``
","
Get the length of the text in pixels for the current font and text scaling. Needs quotes if text contains space(s), comma(s) or quote(s).
"
"
``[<taskname>#textheight,^"<text to measure>^"]``
","
Get the height of the text in pixels for the current font and text scaling. Needs quotes if the text contains space(s), comma(s) or quote(s).
"
"
``[<taskname>#rot]``
","
Get the currently active rotation, expected range 0..3 (0 = 0 degrees, 1 = +90 degrees, 2 = +180 degrees, 3 = +270 degrees).
"
"
``[<taskname>#txs]``
","
Get the currently active text scaling, expected range 1..10, limited to the max. font scaling allowed for the display.
"
"
``[<taskname>#tpm]``
","
Get the currently active text print mode, expected range 0..3, see the ``tpm`` subcommand for details.
"
.. csv-table::
:escape: ^
:widths: 20, 10
"
Example rules for centering a value (time) in a window:
.. code:: none
on centertime do // NB: Comments & extra spaces should be removed to reduce rules size!
if [st7796#iswin,%eventvalue1|2%]=1 // default window: 2
let,120,[st7796#win] // store current window
st77xx,win,%eventvalue1|2% // switch to window
let,121,[st7796#txs] // store textscaling
st77xx,txs,3 // set text scaling
let,122,[st7796#rot] // store rotation
st77xx,rot,%eventvalue2|0% // set rotation, default: 0
let,123,([st7796#width]-[st7796#length,%systm_hm%])/2 // (width - textlength)/2
let,124,([st7796#height]-[st7796#textheight,%systm_hm%])/2 // (height - textheight)/2
st77xx,txtfull,[int#123],[int#124],3,red,black,%systm_hm% // Display time red on black
st77xx,rot,%v122% // restore rotation
st77xx,txs,%v121% // restore text scaling
st77xx,win,%v120% // restore window
endif
endon
on Clock#Time=All,**:** do
asyncevent,centertime=2 // Update the display every minute
endon
","
Display Task is named ``st7796``, using trigger ``st77xx``
Usage: ``asyncevent,centertime[=<win>[,<rot>]]``
"
.. csv-table::
:escape: ^
:widths: 20, 30
"
Generic variables, available for all ``AdafruitGFX_Helper`` enabled plugins, currently: :ref:`P095_page`, :ref:`P096_page`, :ref:`P116_page`, :ref:`P131_page` and :ref:`P141_page`.
","
Generic notes:
* If an argument has comma's or spaces, then that part should be 'wrapped' in either double quotes ``^"``, single quotes ``^'`` or back-ticks ``^```.
* The ``<taskname>`` part is the name of the Device task.
* True(1)/False(0) values can optionally return -1 to indicate an invalid request, like a missing Window Id.
* All sizes, lengths etc. are returned in pixels.
"
"
``[<taskname>#win]``
","
Get the currently active Window Id, expected range: 0..255.
"
"
``[<taskname>#iswin.<windowId>]``
","
Is the request Window Id valid, expected result: 1 = true, 0 = false.
"
"
``[<taskname>#width]``
","
Get the width of the currently active Window and rotation, expected range 0..<largest display dimension>.
"
"
``[<taskname>#height]``
","
Get the height of the currently active Window and rotation, expected range 0..<largest display dimension>.
"
"
``[<taskname>#length.^"<text to measure>^"]``
","
Get the length of the text in pixels for the current font and text scaling. Needs quotes if text contains space(s), comma(s) or quote(s).
"
"
``[<taskname>#textheight.^"<text to measure>^"]``
","
Get the height of the text in pixels for the current font and text scaling. Needs quotes if the text contains space(s), comma(s) or quote(s).
"
"
``[<taskname>#rot]``
","
Get the currently active rotation, expected range 0..3 (0 = 0 degrees, 1 = +90 degrees, 2 = +180 degrees, 3 = +270 degrees).
"
"
``[<taskname>#txs]``
","
Get the currently active text scaling, expected range 1..10, limited to the max. font scaling allowed for the display.
"
"
``[<taskname>#tpm]``
","
Get the currently active text print mode, expected range 0..3, see the ``tpm`` subcommand for details.
"
.. csv-table::
:escape: ^
:widths: 20, 10
"
Example rules for centering a value (time) in a window:
.. code:: none
on centertime do // NB: Comments & extra spaces should be removed to reduce rules size!
if [st7796#iswin.%eventvalue1|2%]=1 // default window: 2
let,120,[st7796#win] // store current window
st77xx,win,%eventvalue1|2% // switch to window
let,121,[st7796#txs] // store textscaling
st77xx,txs,3 // set text scaling
let,122,[st7796#rot] // store rotation
st77xx,rot,%eventvalue2|0% // set rotation, default: 0
let,123,([st7796#width]-[st7796#length.%systm_hm%])/2 // (width - textlength)/2
let,124,([st7796#height]-[st7796#textheight.%systm_hm%])/2 // (height - textheight)/2
st77xx,txtfull,[int#123],[int#124],3,red,black,%systm_hm% // Display time red on black
st77xx,rot,%v122% // restore rotation
st77xx,txs,%v121% // restore text scaling
st77xx,win,%v120% // restore window
endif
endon
on Clock#Time=All,**:** do
asyncevent,centertime=2 // Update the display every minute
endon
","
Display Task is named ``st7796``, using trigger ``st77xx``
Usage: ``asyncevent,centertime[=<win>[,<rot>]]``
"
docs/source/Plugin/P000_commands.repl
+58 -3
View File
@@ -232,17 +232,37 @@
:red:`Internal`","
Run I2C scanner to find connected I2C chips. Output will be sent to the serial port.
``I2Cscanner``
``I2Cscanner[,1]``
Added: 2024-06-14:
With the optional debug argument ``1`` provided, the returned I2C status (error) code will be listed for *all* tested I2C addresses.
Added: 2024-06-14:
Scan is performed at the Low I2C speed configured (default 100 kHz). When having an I2C multiplexer configured, all channels of the multiplexer will also be scanned.
Example output:
.. code-block:: none
4500043 : Info : Command: i2cscanner
>i2cscanner
Standard I2C bus
I2C : Found 0x3c
I2C : Found 0x40
I2C : Found 0x5a
>i2cscanner,1
Standard I2C bus
I2C : Error 2 at 0x01
I2C : Error 2 at 0x02
I2C : Error 2 at 0x03
...
I2C : Error 2 at 0x3f
I2C : Found 0x40
I2C : Error 2 at 0x41
...
I2C : Error 2 at 0x7e
I2C : Error 2 at 0x7f
"
"
Inc","
@@ -363,6 +383,18 @@
``Name,<new name>``"
"
Notify","
:green:`Rules`","
Trigger a notification. Requires the notifier at the numbered index (1..3) to be enabled.
Optionally include the message body (quoted) and subject (quoted) to be passed. NB: The buzzer doesn't support a message body or subject.
Syntax: ``Notify,<notifier>[,<message>[,<subject>]]``
Example:
``Notify,1,'The temperature is currently [ds#temp] degrees!','Temperature warning'``"
"
NTPHost[,<host-name_or_ip>]","
:red:`Internal`","
Set the name of the NTP-host
@@ -371,6 +403,23 @@
``NTPHost,""`` or ``NTPHost,`` -> Clear the NTP host so a default host from pool.ntp.org will be used. (As second argument *is* provided but empty.)"
"
OWScan","
:red:`Internal`","
Scan for & list 1-wire (One Wire = OW) devices on a GPIO pin.
Syntax: ``owscan,<rx-pin>[,<txpin>]``
If no separate TX pin is provided, the RX pin will be used as the TX pin too, as is the normal behavior for 1-wire communication. The separate TX pin is used on a Shelly device when adding the Shelly Temperature add-on (RX = GPIO-0 and TX = GPIO-3).
Example:
.. code-block:: none
>owscan,5
01-6e-56-8c-01-00-00-84 [DS1990A]
"
"
Password","
:red:`Internal`","
Set the password of the unit.
@@ -469,10 +518,16 @@
"
Publish","
:green:`Rules`","
Send command using MQTT broker service. Uses the first enabled MQTT Controller.
Send command using MQTT broker service. The 'Will Retain' option as configured in the MQTT Controller settings is used. Uses the first enabled MQTT Controller.
``Publish,<topic>[,<payload>]``"
"
PublishR","
:green:`Rules`","
Send command using MQTT broker service, with the MQTT 'Will Retain' flag enabled. Uses the first enabled MQTT Controller.
``PublishR,<topic>[,<payload>]``"
"
PutToHTTP","
:green:`Rules`","
*Syntax format 1:*
docs/source/Plugin/P000_events.repl
+63
View File
@@ -196,6 +196,50 @@
Reboot
endon
"
"
``p2pNode#Connected``
Added: 2024-05-01
Triggered when a new ESPEasy p2p node has been seen.
N.B. Only for nodes with a valid unit ID (not 0)
Eventvalues:
- Unit ID
- Node name
- Build number/date
","
.. code-block:: none
on p2pNode#Connected do
LogEntry,'ESPEasy p2p node %eventvalue1% added: %eventvalue2% with build %eventvalue3%'
endon
"
"
``p2pNode#Disconnected``
Added: 2024-05-01
Triggered when a ESPEasy p2p node has been removed from the nodes list.
N.B. Only for nodes with a valid unit ID (not 0)
Eventvalues:
- Unit ID
","
.. code-block:: none
on p2pNode#Disconnected do
LogEntry,`ESPEasy p2p node %eventvalue1% not seen for a while`
endon
"
"
``WiFi#Connected``
@@ -208,6 +252,25 @@
SendToHTTP,url.com,80,/report.php?hash=123abc456&t=[temp2#out]
endon
"
"
``WiFi#Disconnected``
Triggered when the ESP has disconnected from Wi-Fi.
","
.. code-block:: none
On WiFi#Disconnected Do
LongPulse,2,1,1,1,-1 // 0.5 Hz flashing of WiFi led
Endon
.. code-block:: none
On WiFi#Connected Do
GPIO,2,1 // Turn off WiFi led
SendToHTTP,url.com,80,/report.php?hash=123abc456&t=[temp2#out]
Endon
"
"
``WiFi#ChangedAccesspoint``
docs/source/Plugin/P001_commands_GPIO.repl
+9 -7
View File
@@ -11,7 +11,7 @@ Supported hardware: |P000_usedby_GPIO|
"
``GPIO,<GPIO>,<state>``
GPIO: 0 ... 16
GPIO: 0 ... <max supported GPIO pin>
State:
@@ -28,12 +28,12 @@ Supported hardware: |P000_usedby_GPIO|
"
``GPIOtoggle,<GPIO>``
GPIO: 0 ... 16
GPIO: 0 ... <max supported GPIO pin>
","
**Toggle on/off.**.
Toggle the current (output) state of the given GPIO pin.
When executed, it changes the pin mode to output.
When executed, it changes the pin mode to output, for output-capable GPIO pins.
"
"
``LongPulse,<GPIO>,<state>,<duration>``
@@ -130,7 +130,9 @@ Supported hardware: |P000_usedby_GPIO|
"
``Servo,<servo ID>,<GPIO>,<position>``
GPIO: 0 ... **15**
ESP8266 GPIO: 0 ... **15**
ESP32 GPIO: All GPIO pins with output capabilities
Servo: 1/2
@@ -149,7 +151,7 @@ Supported hardware: |P000_usedby_GPIO|
"
``Monitor,G,<GPIO>``
GPIO: 0 ... 16
GPIO: 0 ... <max supported GPIO pin>
","
**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.
@@ -157,7 +159,7 @@ Supported hardware: |P000_usedby_GPIO|
"
``UnMonitor,G,<GPIO>``
GPIO: 0 ... 16
GPIO: 0 ... <max supported GPIO pin>
","
**To cancel the monitor of a GPIO state.**
By the use of the command you will stop receiving events when the GPIO state of that pin is changed from 1 to 0 and from 0 to 1.
@@ -165,7 +167,7 @@ Supported hardware: |P000_usedby_GPIO|
"
``Status,G,<GPIO>``
GPIO: 0 ... 16
GPIO: 0 ... <max supported GPIO pin>
","
**Returns the status of a pin.**
By the use of the command you will receive the status of the relevant pin.
docs/source/Plugin/P001_commands_RTTTL.repl
+10 -6
View File
@@ -11,13 +11,16 @@ Supported hardware: |P000_usedby_RTTTL| (Ringtones etc.)
"
``tone,<gpio>,<tone>,<duration>``
GPIO: 12 ... 16
ESP8266 GPIO: 0 ... 16
ESP32 GPIO: All GPIO pins with output capabilities
Tone: 20 ... 13000 Hz
Duration: 100 ... 15000 msec
","
You should try to use GPIO 12...16 since these generally aren't used.
ESP8266: You should try to use GPIO 12...16 since these generally aren't used.
The recommended tone range is 20 Hz ... 13 kHz.
Up-to 40 kHz should be possible to generate, but will be inaudible for humans.
Frequencies above 30 kHz are not stable and will likely crash the ESP.
@@ -30,13 +33,14 @@ Supported hardware: |P000_usedby_RTTTL| (Ringtones etc.)
"
``rtttl,<gpio>,<value>``
GPIO: 12 ... 16
ESP8266 GPIO: 0 ... 16
ESP32 GPIO: All GPIO pins with output capabilities
Value: d=<duration>,o=<octave>,b=<tempo>,<notes...>
","
You should try to use GPIO 12...16 since these generally aren't used by ESP internal functions.
N.B. Playing a tune is blocking for as long as the tune is playing.
ESP8266: You should try to use GPIO 12...16 since these generally aren't used by ESP internal functions.
Value can be defined like <name_of_melody:duration,octave,beat,notes....>
For example:
docs/source/Plugin/P004.rst
+7
View File
@@ -39,6 +39,13 @@ Supported hardware
.. .. include:: P004_events.repl
Get Config Values
-----------------
Get Config Values retrieves values or settings from the sensor or 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.
.. include:: P004_config_values.repl
Change log
----------
docs/source/Plugin/P004_DS18b20.rst
+3 -2
View File
@@ -227,7 +227,8 @@ Data Acquisition
* **Interval**: How often should the task publish its value (5..15 seconds is normal).
Values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^
* **Name**: Value Name of temperature indicator.
* **Formula**: Optional math conversion. The measured temperature defaults to Celsius. It can be converted to Fahrenheit by entering this formula:
@@ -251,7 +252,7 @@ Rules examples
.. code-block:: none
On Temperature1#Celsius Do
If [Temperature1#Celsius]>37
If %eventvalue1%>37
NeoPixelAll,255,0,0 //Your body temperature is too high!
Else
NeoPixelAll,0,255,0 //Body temperature is OK.
docs/source/Plugin/P004_config_values.repl
+46
View File
@@ -0,0 +1,46 @@
.. csv-table::
:header: "Config value", "Information"
:widths: 20, 30
"
| ``[<taskname>#SensorStats.<sensornr>.Success]``
| ``<sensornr>``: The number of the device address within the configuration, range 1..4.
","
| Returns the number of successful reads for this sensor as shown in the settings page.
"
"
| ``[<taskname>#SensorStats.<sensornr>.Retry]``
| ``<sensornr>``: The number of the device address within the configuration, range 1..4.
","
| Returns the number of retries for this sensor as shown in the settings page.
"
"
| ``[<taskname>#SensorStats.<sensornr>.Failed]``
| ``<sensornr>``: The number of the device address within the configuration, range 1..4.
","
| Returns the number of failed reads for this sensor as shown in the settings page.
"
"
| ``[<taskname>#SensorStats.<sensornr>.InitFailed]``
| ``<sensornr>``: The number of the device address within the configuration, range 1..4.
","
| Returns the number of failed initialization-reads (second retry failed too) for this sensor as shown in the settings page.
"
"
| ``[<taskname>#SensorStats.<sensornr>.Resolution]``
| ``<sensornr>``: The number of the device address within the configuration, range 1..4.
","
| Returns the resolution in bits for this sensor as shown in the settings page.
"
"
| ``[<taskname>#SensorStats.<sensornr>.Address]``
| ``<sensornr>``: The number of the device address within the configuration, range 1..4.
","
| Returns the formatted Device Address, including the device type, for this sensor as shown in the settings page.
"
docs/source/Plugin/P011.rst
+65 -4
View File
@@ -1,4 +1,4 @@
.. include:: ../Plugin/_plugin_substitutions_p01x.repl
.. include:: ../Plugin/_plugin_substitutions_p01x.repl
.. _P011_page:
|P011_typename|
@@ -26,22 +26,83 @@ Supported hardware
|P011_usedby|
.. Commands available
.. ^^^^^^^^^^^^^^^^^^
This plugin supports the Pro Mini Extender, that's a software solution installed on an Arduino Nano, providing 5 available analog input/output pins and 14 digital input/output pins.
.. .. include:: P011_commands.repl
The Pro Mini Extender software has to be manually installed on the Arduino Nano (or a Chinese clone), using the ``MiniProExtender`` software project from this `ESPEasySlaves repository <https://github.com/letscontrolit/ESPEasySlaves>`_ via the Arduino IDE.
After installing the software on the Arduino Nano, the simplest solution is to power the PME with 3.3V, even if it's specified for 5V, so no level converter is needed for the I2C connection with the ESP, that only allows for 3.3V signal levels. The 3.3V power has to be connected to the 5V pin on the Arduino Nano, **not** on the 3.3V pin, as that's a low-power output-only pin!
NB: This software can also be installed on other Arduino models, that support I2C, Analog and Digital pins, but this hasn't been actively tested. Depending on the available IO pins, some of the features may not match with the Arduino Nano.
Device Configuration
--------------------
.. image:: P011_DeviceConfiguration.png
* **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.
Sensor
^^^^^^
* **Port** Select the port (pin) of the Pro Mini Extender that is addressed by this task. For a *Digital* or *Input (Switch)* the range is 0..13, for an *Analog* input, the available pins are 0..3 and 6..7, as A4 and A5 are the (fixed) I2C pins of the Arduino Nano.
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`
Device Settings
^^^^^^^^^^^^^^^
* **Port Type**:
.. image:: P011_PortTypeOptions.png
* *Digital*: An On/Off Input/Output type of port, every **Interval** the pin is read and the state is made available in the **Value** field.
* *Analog*: Read the current analog value of the port.
* *Input (switch)*: Act like an input switch, the pin is read every 20 msec, and if the state changes, the new state is reported as an event, with the new value. The **Interval** is ignored when this Port Type is selected.
Data Acquisition
^^^^^^^^^^^^^^^^
This group of settings, **Single event with all values**, **Send to Controller** and **Interval** settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.
**Interval** By default, Interval will be set to 60 sec. It is the frequency used to read sensor values and send these to any Controllers configured for this device.
Values
^^^^^^
The single **Value** available holds the last digital, analog or input (switch) state value.
Commands available
^^^^^^^^^^^^^^^^^^
.. include:: P011_commands.repl
.. Events
.. ~~~~~~
.. .. include:: P011_events.repl
Get Config Values
^^^^^^^^^^^^^^^^^
Get Config Values retrieves values or settings from the sensor or 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.
.. include:: P011_config_values.repl
Change log
----------
.. versionchanged:: 2.0
...
|added| 2024-03: Add Input (switch) option.
|added|
Major overhaul for 2.0 release.
docs/source/Plugin/P011_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

docs/source/Plugin/P011_PortTypeOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

docs/source/Plugin/P011_commands.repl
+53
View File
@@ -0,0 +1,53 @@
.. csv-table::
:header: "Command", "Extra information"
:widths: 20, 30
"
``extgpio,<pin>,<0|1>``
``<pin>`` : The IO pin on the PME board, range 0..13 for Digital output.
``<0|1>`` : Select 0 for Off (low), and 1 for On (high) level output
","
Switch the pin to either low or high level output.
"
"
``extpwm,<pin>,<level>``
``<pin>`` : The IO pin on the PME board, range 0..7 for Analog output.
``<level>`` : The PWM level, range 0..255
","
Set the Analog pin (0..7) to the PWM level, where 0 = 0% and 255 = 100% of the VCC voltage the PME is running at.
"
"
``extpulse,<pin>,<0|1>,<duration>``
``<pin>`` : The IO pin on the PME board, range 0..13 for Digital output.
``<0|1>`` : Select 0 for Off (low), and 1 for On (high) level output
``<duration>`` : The time in milliseconds the IO pin state should be set, after which it is restored in the previous state.
","
Switch the pin to either low or high level output, and after the duration has passed, return to the previous state.
"
"
``extlongpulse,<pin>,<0|1>,<duration>``
``<pin>`` : The IO pin on the PME board, range 0..13 for Digital output.
``<0|1>`` : Select 0 for Off (low), and 1 for On (high) level output
``<duration>`` : The time in **seconds** the IO pin state should be set, after which it is restored in the previous state.
","
Switch the pin to either low or high level output, and after the duration (seconds!) has passed, return to the previous state.
"
"
``status,ext,<pin>``
``<pin>`` : The IO pin on the PME board, range 0..13 for Digital output, range 20..27 for the Analog pins A0..A7.
","
Report the current state/value for the pin selected.
"
docs/source/Plugin/P011_config_values.repl
+20
View File
@@ -0,0 +1,20 @@
.. csv-table::
:header: "Config value", "Information"
:widths: 20, 30
"
``[<taskname>#D.<port>]``
``<port>`` : Range 0..13, corresponding with D0..D13 on the PME.
","
Returns the current status (0/1) from the requested Digital port (pin) of the Pro Mini Extender.
"
"
``[<taskname>#A.<port>]``
``<port>`` : Range 0..3 and 6..7, corresponding with A0..A7 on the PME.
","
Returns the current value (0..1023) at the requested Analog port (pin) of the Pro Mini Extender.
Port A4 and A5 should be avoided, as that's occupied by the I2C connection at the PME. There is no check in the code to block those pins!
"
docs/source/Plugin/P020.rst
+97 -7
View File
@@ -26,23 +26,111 @@ Supported hardware
|P020_usedby|
Configuration
-------------
.. image:: P020_DeviceConfiguration.png
* **Name** In the Name field a unique name should be entered.
* **Enabled** When unchecked the plugin is not enabled.
Sensor
^^^^^^
See: :ref:`SerialHelper_page`
Device Settings
^^^^^^^^^^^^^^^
**TODO**: Complete this documentation...
* **TCP Port**: The port for an external network client to read the data from, range 1..65535. The used port number must be unique within the device.
.. Commands available
.. ^^^^^^^^^^^^^^^^^^
* **Baud Rate / Serial config**: See *Serial helper configuration*, above.
.. .. include:: P020_commands.repl
* **Event Processing**: Select the type of data that is expected, to enable correct preprocessing. Available options:
.. Events
.. ~~~~~~
.. image:: P020_EventProcessingOptions.png
.. .. include:: P020_events.repl
* *None*: No special processing, what is received is sent out to the network client, not generating an event.
* *Generic*: No special processing, received data is sent to the network client, and an event ``!Serial#<message>``, containing the message as is, is generated. Spaces and newlines are processed as configured below.
* *RFLink*: Specifically designed for receiving serial data from RFLink devices, it follows this process:
* Remove the regular RFLink ``20;xx;`` prefix
* Check for prefix ``ESPEASY;``, if found, remove the prefix and generate event ``RFLink#<message>``. The ``<message>`` will contain commands to be handled by ESPEasy.
* If previous prefix is not found, generate event ``!RFLink#<message>``, containing the entire received data. Spaces and newlines are processed as configured below.
*Also see the* **Multiple lines processing** *option, below.*
* *P1 WiFi Gateway*: Process the data, received from a P1 Energy meter, that does a checksum validation, as included in the message. No separate data values are available in ESPEasy, these are usually handled by Home automation systems that support the P1 protocol via TCP network communication. An event ``<TaskName>#Data`` is generated when a valid P1 packet is received.
Replacing spaces or newlines should be **disabled** for the P1 protocol data to be handled properly as these replacements will disturb the checksum calculation, and also, the **Multiple lines processing** should be disabled if the data is to be handled as P1 protocol data, as that does contain newlines.
.. spacer
* **P1 #data event with message**: When enabled, the *P1 WiFi Gateway* Event Processing option will include the received message. **WARNING** This may easily cause memory overflow exceptions, especially when running on ESP8266 or other low-memory situations!
When selecting the **Event processing** options *Generic* or *RFLink*, after submitting the page will show extra options for the events generated:
.. image:: P020_EventOptions.png
* **Use Serial Port as eventname**: Instead of the default ``!Serial#<data>`` event, the name of the configured serial port will be used: (**Only** available for *Generic* Event processing)
.. spacer
* *(Unchecked)* -> ``Serial``
* *HW Serial0* -> ``serial0``
* *HW Serial0 swap* -> ``serial0``
* *HW Serial1* -> ``serial1``
* *HW Serial2* -> ``serial2``
* *SW Serial* -> ``serialsw``
* *I2C Serial* -> ``seriali2c``
* *USB HWCDC* -> ``serialhwcdc``
* *USB CDC* -> ``serialcdc``
.. spacer
* **Append Task Number to eventname**: Will append the task number to the event name, f.e. ``Serial8`` or ``RFLink12`` when task 8 or 12 is in use for this plugin. Can be combined with **Use Serial Port as eventname** if that is option is shown, resulting f.e. in ``serial0swap6`` etc. (Only available for *Generic* and *RFLink* Event processing)
.. spacer
* **Replace spaces in event by**: Here a single character can be selected to replace all spaces during receiving the data.
* **Replace newlines in event by**: Here a single character can be selected to replace all newlines during receiving the data. When enabled, all linefeeds are replaced, and all carriage returns (if any) are discarded.
.. image:: P020_ReplaceCharInEventOptions.png
The available set of replacement characters is ``, ; : . ! ^ | / \`` (comma, semicolon, colon, period, exclamation, caret, pipe, slash and backslash). When set to None, no replacement will be done.
* **Process events without client**: By default, if no network client is connected, no serial data will be received and processed either. Enabling this option enables receiving data and generating events without a TCP client connected.
* **Multiple lines processing**: When enabled, all received data will be split at a linefeed and sent out/event generated as separate messages.
* **RX Receive timeout (mSec)**: If parts of serial data packets are somewhat delayed, but should still be handled as a single message, then the delay to wait for the next part can be configured here. 0 disables the delay.
* **Reset target after init**: Select a GPIO pin that should be pulled low once during initialization of the plugin, used to synchronize the external serial data source with the plugin.
* **RX Buffer size (bytes)**: To not overburden the memory use of the plugin, the buffer size is set rather low. Some serial devices, like energy meters may require a larger buffer if the message exceeds this size. Range: 256..1024.
Led
^^^
* **Led enabled**: To enable a *data is being processed* activity led.
* **Led pin**: The GPIO pin the Led is connected to.
* **Led inverted**: Iverts the on/off state for the Led.
Data Acquisition
^^^^^^^^^^^^^^^^
The Data Acquisition and Send to Controller settings are standard available configuration items. Send to Controller only when one or more Controllers are configured. *Single event with all values* option is not applicable for this plugin.
Commands
~~~~~~~~
.. include:: P020_commands.repl
Change log
----------
@@ -50,6 +138,8 @@ Change log
.. versionchanged:: 2.0
...
|changed| 2022-12-13: Merge of P020 and P044 to reduce code size and combine features, as P044 was initially started as a spin-off from P020, but not evolved with the P020 features.
|added|
Major overhaul for 2.0 release.
docs/source/Plugin/P020_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 68 KiB

docs/source/Plugin/P020_EventOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

docs/source/Plugin/P020_EventProcessingOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

docs/source/Plugin/P020_ReplaceCharInEventOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

docs/source/Plugin/P020_commands.repl
+37
View File
@@ -0,0 +1,37 @@
.. csv-table::
:header: "Command", "Extra information"
:widths: 20, 30
"
``serialsend,<content to send>``
``<content to send>``: Text that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the serial port.
","
Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.
"
"
``ser2netclientsend,<content to send>``
``<content to send>``: Text that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the network client.
","
This command will only send data to the network client, when there is an active connection.
Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the network client. No extra data is added, other than any (system) variables that are included, being replaced.
"
"
``serialsendmix,'<content to send>'[,...]``
``<content to send>``: Text and/or hex byte(s) (having 0x prefix) that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the serial port.
","
This command requires quotes to be used if spaces or commas are part of the content.
Any data can be sent, even if it can not be typed in a text content, by specifying that as a separate argument: ``serialsendmix,'text, optionally including spaces or commas',0xXX,'0xXXxx XX,xx-XX:xx'``
``'text, optionally including spaces or commas'``: Any text content to be sent to the serial port. Can contain variables. Quotes are only required if spaces or commas (separators) are used.
``0xXX``: A single character in hexadecimal notation (range: 0x00..0xFF), that is appended to the data to send.
``'0xXXxx XX,xx-XX:xx'``: A sequence of hexadecimal values (range: 0x00..0xFF), that *can* be separated by a space, comma, dash, colon, semicolon or period, or are just entered adjecent. Only the first 2 characters should be ``0x`` or ``0X``, the rest is interpreted as hex bytes, and appended to the string to send. Quotes are only required if space or comma separators are used.
Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.
"
docs/source/Plugin/P029.rst
+3
View File
@@ -113,6 +113,7 @@ Relevant Settings:
* Plugin: Output - Domoticz MQTT Helper
* 1st GPIO: 12 (the relay)
* IDX: 475
* Invert On/Off value: To ease the use of this plugin, without the need for rules, an Invert option has been added. This will cause the GPIO pin (and ``Output`` value) to be set to 1 when the Domoticz device is in Off state, and 0 for the On state.
Rules
@@ -184,6 +185,8 @@ Change log
.. versionchanged:: 2.0
...
|added| 2024-03: Add Invert On/Off value option.
|added|
Major overhaul for 2.0 release.
docs/source/Plugin/P029_Domoticz_Helper.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 34 KiB

After

Width:  |  Height:  |  Size: 21 KiB

docs/source/Plugin/P034.rst
+58 -4
View File
@@ -1,4 +1,4 @@
.. include:: ../Plugin/_plugin_substitutions_p03x.repl
.. include:: ../Plugin/_plugin_substitutions_p03x.repl
.. _P034_page:
|P034_typename|
@@ -21,10 +21,64 @@ Maintainer: |P034_maintainer|
Used libraries: |P034_usedlibraries|
Supported hardware
------------------
.. Supported hardware
.. ------------------
.. .. |P034_usedby|
Introduction
------------
Specifications:
* Temperature (-20 to +60C)
* Humidity (20-95 % rel. humidity)
Settings
--------
.. image:: P034_DeviceConfiguration.png
* **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 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`
Device Settings
^^^^^^^^^^^^^^^
This device has no further configuration settings.
Data Acquisition
^^^^^^^^^^^^^^^^
This group of settings, **Single event with all values**, **Send to Controller** and **Interval** settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.
* **Interval** By default, Interval will be set to 60 sec. It is the frequency used to read sensor values and send these to any Controllers configured for this device.
Values
^^^^^^
The names for the values are initially set to a default name, but can be changed if desired. Also, a formula can be entered to re-calculate the value before display/sending to a controller, and the number of decimals can be changed, for Temperature, usually 1 decimal is enough to be displayed (value will be rounded).
Where to buy
------------
.. csv-table::
:header: "Store", "Link"
:widths: 5, 40
"AliExpress","`Link 1 ($) <http://s.click.aliexpress.com/e/cg1fhDDI>`_"
|affiliate|
|P034_usedby|
.. Commands available
.. ^^^^^^^^^^^^^^^^^^
docs/source/Plugin/P034_DHT12.rst
-71
View File
@@ -1,71 +0,0 @@
.. include:: ../Plugin/_plugin_substitutions_p03x.repl
.. _P034_DHT12_page:
DHT12
=====
|P034_typename|
|P034_status|
Introduction
------------
Specifications:
* Temperature (-20 to +60C)
* Humidity (20-95 % rel. humidity)
Wiring
------
.. code-block:: none
ESP S8
GPIO (X) <--> TX
GPIO (X) <--> RX
Power
5.0V <--> VCC
GND <--> GND
Setup
-----
Rules examples
--------------
.. code-block:: none
//Code below...
Indicators (recommended settings)
---------------------------------
.. csv-table::
:header: "Indicator", "Value Name", "Interval", "Decimals", "Extra information"
:widths: 8, 5, 5, 5, 40
"XXXXXX", "N/A", "", "", ""
Where to buy
------------
.. csv-table::
:header: "Store", "Link"
:widths: 5, 40
"AliExpress","`Link 1 ($) <http://s.click.aliexpress.com/e/cg1fhDDI>`_"
|affiliate|
More pictures
-------------
docs/source/Plugin/P034_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

docs/source/Plugin/P037.rst
+7 -1
View File
@@ -190,11 +190,17 @@ Option: Limit events being generated
* **Max. # events in event queue**: As a protection against event-overflow this configures a check for the queue-length, so if more than the selected number of events is still in the queue, new events will be discarded until some events are processed, and the remaining is less than this count. When set to 0 this check is disabled.
Option: Modify separater character in events
Option: Modify separator character in events
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* **To replace by comma in event**: Select a character that is to be replaced by a comma, before it is put into the event-queue. There is a limited set of characters that can be replaced, to avoid ending up with malformed events.
Available options:
.. image:: P037_ReplaceByCommaOptions.png
The available set of replacement characters is ``! @ $ % ^ & * ; : . | / \`` (exclamation, at, dollar, percent, caret, ampersand, semicolon, colon, period, pipe, slash and backslash). When set to None, no replacement will be done.
This can be used to 'transform' the content of a JSON message so the used separator is a comma, for easier use in rules.
Topic Subscriptions
docs/source/Plugin/P037_ReplaceByCommaOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

docs/source/Plugin/P043.rst
+70 -10
View File
@@ -1,4 +1,4 @@
.. include:: ../Plugin/_plugin_substitutions_p04x.repl
.. include:: ../Plugin/_plugin_substitutions_p04x.repl
.. _P043_page:
|P043_typename|
@@ -21,20 +21,77 @@ Maintainer: |P043_maintainer|
Used libraries: |P043_usedlibraries|
Supported hardware
------------------
|P043_usedby|
.. Commands available
.. ^^^^^^^^^^^^^^^^^^
Description
-----------
.. .. include:: P043_commands.repl
Every minute the set schedule will be checked for a match, and if a value for a scheduled time is set, the GPIO will be set to that state (On/Off) when configured, or when no GPIO is configured and the value is not 0 or empty, an event is generated with the field number that caused the trigger, and another event with the set value if the Number Output Values is set to Dual or higher.
.. Events
.. ~~~~~~
Configuration
-------------
.. .. include:: P043_events.repl
.. image:: P043_DeviceConfiguration.png
* **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.
Sensor
^^^^^^
* **GPIO -> Clock event** Select a GPIO that will get the stated as configured for the Day,Time. When a GPIO is configured, the allowed valies for a scheduled time will be empty, Off and On only.
Device Settings
^^^^^^^^^^^^^^^
* **Nr. of Day,Time fields**: Select a number between 1 and 16 for the number of Day,Time fields to be available. Will be applied after the page is submitted. (Default: 8)
* **Value input On/Off only**: When checked, the selection for Value will be for On/Off (or empty) only, to avoid misconfiguration for less experienced users, and the Output variable response the same as if a GPIO was selected. The default is unchecked.
.. image:: P043_GPIO_Enabled.png
* **Day,Time X**: Select the Day and Time that should be checked. For Limited builds the day and time have to be entered manually, for other builds, the Day can be selected from a combobox, and the time can be selected from a predefined list and set to a desired time.
For Day, the available options are All, Sun, Mon, Tue, Wed, Thu, Fri, Sat, Wrk (workday), Wkd (weekend).
.. image:: P043_DayOptions.png
For time, besides the 24h HH:MM notation, there can also be chosen to use ``%sunrise%`` or ``%sunset%``, optionally with an offset in hours, minutes or seconds like ``%sunrise-1h%`` or ``%sunset+30m%``.
.. image:: P043_TimeOptions.png
Output Configuration
^^^^^^^^^^^^^^^^^^^^
* **Number Output Values**: Select Single (default), Dual, Triple or Quad. The Triple and Quad options aren't actually used in this plugin.
Data Acquisition
^^^^^^^^^^^^^^^^
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.
Values
^^^^^^
The default names for the values are named ``Output``, and get a numeric suffix for the Dual, Triple and Quad configuration.
Commands available
^^^^^^^^^^^^^^^^^^
.. include:: P043_commands.repl
Events
~~~~~~
.. include:: P043_events.repl
Get Config Values
^^^^^^^^^^^^^^^^^
Get Config Values retrieves values or settings from the sensor or 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.
.. include:: P043_config_values.repl
Change log
----------
@@ -42,6 +99,9 @@ Change log
.. versionchanged:: 2.0
...
|added| 2023-12-16:
Selectors for Day and Time, ``%sunrise%`` and ``%sunset%`` support, ``config`` command and get config values.
|added|
Major overhaul for 2.0 release.
docs/source/Plugin/P043_DayOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

docs/source/Plugin/P043_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

docs/source/Plugin/P043_GPIO_Enabled.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

docs/source/Plugin/P043_TimeOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

docs/source/Plugin/P043_commands.repl
+33
View File
@@ -0,0 +1,33 @@
.. csv-table::
:header: "Command Syntax", "Extra information"
:widths: 30, 20
"
| ``config,task,<taskName>,SetTime,<timeIndex>,<timeString>[,<value>]``
Change the configuration of the plugin for the timeIndex provided:
``config,task``: The Config command to change a setting for a task. Not case-sensitive.
``<taskName>``: The name of the task to be changed.
``SetTime``: Literal command-text recognized by the plugin to set the time and optional value. Not case-sensitive.
``<timeIndex>``: The Day,Time fields *number* as shown in the UI. Has to be within the allowed range 1..Nr. of Day,Time field setting.
``<timeString>``: A time string as can be entered in the UI, a day (All,Sun, Mon,Tue,Wed,Thu,Fri,Sat,Wrk (workday),Wkd (weekend)) and a time (HH:MM or %Sunrise%/%Sunset%). When configuring for sunrise of sunset, an offset in hours, minutes or seconds can be provided by using ``%sunrise-1h%`` or ``%sunset+30m%`` etc. To avoid the sunrise or sunset time of today to be inserted, instead of ``%`` a ``$`` must be used! If an invalid ``<timeString>`` is provided, ``All,00:00`` will be stored!
``<value>``: The value to be set. If a GPIO is configured or the setting 'Value input On/Off only' is enabled, a 0 will configure Off and 1 will configure On. When not using a GPIO or the 'Value input On/Off only' setting is unchecked, the value will be stored as provided. When having value 0 set, **no event will be generated** when this time is triggered!
","
This (generic) command allows to update the configuration.
.. warning:: Every time this command is used, the configuration is saved to flash storage. When changing this often, the flash memory may wear out quickly!
Example command to use, when using ``%Sunrise%``/``%Sunset%``:
- ``config,task,Clock,settime,1,Wrk,$sunrise-1h$,1``
Will be stored like ``Wrk,%sunrise-1h%`` in Day,Time field 1, and Value set to 1, or ``On`` when having a GPIO configured or **Value input On/Off only** enabled.
"
docs/source/Plugin/P043_config_values.repl
+23
View File
@@ -0,0 +1,23 @@
.. csv-table::
:header: "Config value", "Information"
:widths: 20, 30
"
``[<taskname>#GetTimeX]``
","
Returns the configured Day,Time string for line X (Range: 1..Nr. of Day,Time fields), as shown in the UI.
Examples:
- ``All,06:00``
- ``Wrk,%sunset-1h%``
"
"
``[<taskname>#GetValueX]``
","
Returns the configured value for line X (Range: 1..Nr. of Day,Time fields), with a twist:
If a GPIO is configured, or the setting 'Value input On/Off only' is checked, a 0 is returned for Off and 1 for On (the stored value is actualy 1 higher)
When no GPIO is configured and the setting 'Value input On/Off only' is unchecked, the shown value is returned.
"
docs/source/Plugin/P043_events.repl
+14
View File
@@ -0,0 +1,14 @@
.. csv-table::
:header: "Event", "Example"
:widths: 30, 20
"
``clock#Output`` The value provided with this event is the field (1..Nr. of Day,Time fields) that was triggered.
``clock#Output2`` When the 'Number Output Values' is set to Dual, Triple or Quad, and a GPIO is configured or 'Value input On/Off only' is checked the On (1) or Off (0) value is included as an event argument (``%eventvalue1%``).
If no GPIO is configured and 'Value input On/Off only' is unchecked, the configured value is provided as ``%eventvalue1%``.
Events are only generated if the value is not set to 0 or empty.
","
"
docs/source/Plugin/P044.rst
+32 -7
View File
@@ -26,23 +26,46 @@ Supported hardware
|P044_usedby|
.. note:: This plugin is now merged (back) into :ref:`P020_page` where it initially was forked off from, with using some predefined settings.
Configuration
-------------
.. image:: P044_DeviceConfiguration.png
* **Name** In the Name field a unique name should be entered.
* **Enabled** When unchecked the plugin is not enabled.
Sensor
^^^^^^
See: :ref:`SerialHelper_page`
Device Settings
^^^^^^^^^^^^^^^
**TODO**: Complete this documentation...
* **TCP Port**: The port for an external network client to read the data from, range 1..65535. The used port number must be unique within the device.
.. Commands available
.. ^^^^^^^^^^^^^^^^^^
* **Baud Rate / Serial config**: See *Serial helper configuration*, above.
.. .. include:: P044_commands.repl
* **P1 #data event with message**: When enabled, the *P1 WiFi Gateway* Event Processing option will include the received message. **WARNING** This may easily cause memory overflow exceptions, especially when running on ESP8266 or other low-memory situations!
.. Events
.. ~~~~~~
* **Process events without client**: By default, if no network client is connected, no serial data will be received and processed either. Enabling this option enables receiving data and generating events without a TCP client connected.
* **RX Receive timeout (mSec)**: If parts of serial data packets are somewhat delayed, but should still be handled as a single message, then the delay to wait for the next part can be configured here. 0 disables the delay.
* **Reset target after init**: Select a GPIO pin that should be pulled low once during initialization of the plugin, used to synchronize the external serial data source with the plugin.
Led
^^^
* **Led enabled**: To enable a *data is being processed* activity led.
* **Led pin**: The GPIO pin the Led is connected to.
* **Led inverted**: Iverts the on/off state for the Led.
.. .. include:: P044_events.repl
Change log
----------
@@ -50,6 +73,8 @@ Change log
.. versionchanged:: 2.0
...
|changed| 2022-10-08: Merge of P020 and P044 to reduce code size and combine features, as P044 was initially started as a spin-off from P020, but not evolved with the P020 features.
|added|
Major overhaul for 2.0 release.
docs/source/Plugin/P044_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

docs/source/Plugin/P044_ReplaceCharInEventOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

docs/source/Plugin/P047.rst
+36 -7
View File
@@ -40,6 +40,15 @@ Supported hardware
.. image:: P047_BeFlESensor.png
* Adafruit:
Where to buy: `Adafruit webshop or local distributor <https://www.adafruit.com/product/4026>`_
Arduino library: `Adafruit SeeSaw library on GitHub.com <https://github.com/adafruit/Adafruit_Seesaw>`_ (only uswed for inspiration)
.. image:: P047_Adafruit4026.png
:height: 115px
Though not directly applicable, as it is about selecting an Analog Soil-moisture sensor, `this Youtube video <https://www.youtube.com/watch?v=IGP38bz-K48>`_ has usable tips on finding a reliable sensor.
Configuration
@@ -58,30 +67,42 @@ The available settings here depend on the build used. At least the **Force Slow
* **I2C Address (Hex)**: The address the device is using. The default I2C address is prefilled, and can be configured to use a different address, see below. As this can be any valid I2C address in range: 0x01..0x7F, it has to be typed here, using a hexadecimal value.
For the Adafruit I2C Capacitive Moisture sensor, only addresses 0x36..0x39 can be configured, by connecting the A0/A1 address soldering pads. For this sensor only these addresses can be selected.
.. note:: If the device doesn't stay enabled after setting the Enabled checkbox, then possibly the address of the sensor is changed from the default. The I2C Scan on the Tools page can be used to detect what I2C device addresses are in use (disconnect other I2C devices to avoid confusion). Possibly, another device-model is listed for this sensor, but that is caused by the feature that it can have any address set that's in the I2C allowed range of 0x00 to 0x7F.
Device Settings
^^^^^^^^^^^^^^^^
* **Sensor model**: Select the model of the used sensor. When changing the selection the page will be reloaded to adjust the content of the screen.
* **Sensor model**: Select the model of the used sensor. When changing the selection the page will be reloaded to adjust the available configuration options, tailored to the selected sensor.
.. image:: P047_SensorModelOptions.png
* *Catnip electronics/miceuz (default)*: The originally supported soil moisture sensor, that supports temperature, moisture and light measurement, has a sleep-mode, and can report a version number, to optionally validate if the sensor is supported.
* *BeFlE*: An I2C soil moisture sensor that supports temperature and moisture measurement. There is no sleep mode or version check available.
* *BeFlE v2.2*: An I2C soil moisture sensor that supports temperature and moisture measurement. There is no sleep mode or version check available.
When selecting the BeFlE sensor, only these **Device Settings** will be available:
* *BeFlE v3.x*: An I2C soil moisture sensor that supports temperature and moisture measurement, has a low-power Sleep mode and can report it's version, but this is not explicitly checked.
* *Adafruit (4026)*: An I2C soil moisture sensor that supports temperature and moisture measurement. There is no sleep mode available, and the version is only logged at startup.
When selecting the BeFlE v2.2 sensor, only these **Device Settings** will be available:
.. image:: P047_SensorModelBeFlE.png
* **Send sensor to sleep**: When not actively reading the sensor, the device can be set to sleep-mode, to conserve some power. (Catnip sensor only).
When selecting the BeFlE v3.x sensor, only these **Device Settings** will be available:
.. image:: P047_SensorModelBeFlEv3.png
* **Send sensor to sleep**: When not actively reading the sensor, the device can be set to sleep-mode, to conserve some power. (Catnip and BeFlE v3 sensors only).
* **Check sensor version**: To validate if the sensor is of the correct mode, the version can be validated. (Catnip sensor only).
* **Change sensor address**: To use multiple sensors connected to a single ESP unit, a sensor can be configured to use a different I2C address. To change that address, this checkbox has to be enabled, and a different I2C address should be entered in the **Change I2C Address to (Hex)** field in hexadecimal format, range: 0x01..0x7F.
* **Change sensor address**: To use multiple sensors connected to a single ESP unit, a sensor can be configured to use a different I2C address. To change that address, this checkbox has to be enabled, and a different I2C address should be entered in the **Change I2C Address to (Hex)** field in hexadecimal format, range: 0x01..0x7F. This option isn't available for the Adafruit sensor.
* **Change I2C Addr. to (Hex)**: The new address to be used by the sensor. The change will be applied the next time the task is enabled. The **I2C Address (Hex)** field, above, will be updated with the new value. After the change is applied, **the tasks Settings have to be saved once more to save the new address** as the address to use.
* **Change I2C Addr. to (Hex)**: The new address to be used by the sensor. The change will be applied the next time the task is enabled. The **I2C Address (Hex)** field, above, will be updated with the new value. After the change is applied, **the tasks Settings have to be saved once more to save the new address** as the address to use. This option isn't available for the Adafruit sensor.
When using the I2C scanner, the changed address will show up, but it probably will not show the sensor name, as only the original I2C address is added to the list. NB: Not all builds show known names for sensors to reduce the build binary size.
.. note:: The newly set address is permanently stored in the sensor, and can be changed again at a later time if desired.
@@ -97,7 +118,9 @@ Values
The measured values are available in ``Temperature``, ``Moisture`` and ``Light``. A formula can be set to recalculate. The number of decimals is by default set to 2, and can be set to 0 for ``Moisture``, as no decimals are provided from the measurement.
NB: The BeFlE sensor doesn't support a Light value, so that won't be available if that **Sensor model** is selected.
NB: The BeFlE and Adafruit sensors don't support a Light value, so that won't be available if that **Sensor model** is selected.
NB2: The Adafruit sensor has a different range for the moisture values: 200..2000 compared to the Catnip and BeflE sensors: 1..800, so any moisture calibration has to be based on actual observation, and not on absolute numbers.
.. Commands available
@@ -116,6 +139,12 @@ Change log
.. versionchanged:: 2.0
...
|added| 2024-05: Add support for BeFlE v3.x I2C moisture sensor.
|added| 2024-04: Add support for Adafruit I2C moisture sensor.
|added| 2023-03: Add support for BeFlE v2.2 I2C moisture sensor.
|added|
Major overhaul for 2.0 release.
docs/source/Plugin/P047_Adafruit4026.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 365 KiB

docs/source/Plugin/P047_SensorModelBeFlE.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 10 KiB

docs/source/Plugin/P047_SensorModelBeFlEv3.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

docs/source/Plugin/P047_SensorModelOptions.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.1 KiB

After

Width:  |  Height:  |  Size: 15 KiB

docs/source/Plugin/P064.rst
+51 -16
View File
@@ -26,43 +26,75 @@ Description
The APDS9960 sensor provides Gesture, Proximity and Ambient Light data or R/G/B color values from the light sensor, depending on the Plugin Mode. After changing the Plugin Mode, the Values arguments may need to be adjusted according to their function (Gesture, Proximity, Light or R, G, B). If the initial Values names are used, they will be replaced when switching the Plugin Mode, and the settings are actually saved.
Device Configuration
--------------------
.. image:: P064_DeviceConfiguration.png
* **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 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`
There is only 1 I2C address available for this sensor, ``0x39`` (not shown).
The Gain, LED Drive and LED Boost parameters may need adjustment from the defaults as some of the low-cost clone sensors aren't as carefully calibrated as the original SparkFun or AdaFruit sensors. The suggested defaults are taken from the original SparkFun driver software settings. When first configuring this plugin it is advised to start with these default settings, and adjust when the sensor isn't responding as required.
Device Settings
^^^^^^^^^^^^^^^
* **Plugin Mode**: Select the desired operation mode.
.. image:: P064_PluginModeOptions.png
* *Gesture/Proximity/Ambient Light Sensor*: Will measure the Gesture, Proximity and Ambient light values. If **Separate Gesture events** is disabled, then events will be generated when a Gesture is detected. Also, when **Interval** is set, events are generated.
* *R/G/B Colors*: Will measure the R, G and B components of the current Ambient light condition. Will generate events if **Interval** is set.
For the R/G/B Colors mode, only Light Sensor Gain and Light Sensor LED Drive parameters are available. They correspond with the Ambient Light Sensor Gain and Proximity/ALS LED Drive parameters (and use the same settings storage), but with different labels.
NB: Defaults are *not* automatically set after adding the plugin!
Gesture parameters
------------------
^^^^^^^^^^^^^^^^^^
Gesture Gain: Selection of the gain factor, select from 1x, 2x, 4x (default) or 8x.
* **Gesture Gain**: Selection of the gain factor, select from 1x, 2x, 4x (default) or 8x.
Gesture LED Drive: Selection of the current to drive the Gesture IR LED, select from 100 mA (default), 50 mA, 25 mA or 12.5 mA.
* **Gesture LED Drive**: Selection of the current to drive the Gesture IR LED, select from 100 mA (default), 50 mA, 25 mA or 12.5 mA.
Gesture LED Boost: Selection of the LED Boost factor, select from 100%, 150%, 200% or 300% (default).
* **Gesture LED Boost**: Selection of the LED Boost factor, select from 100%, 150%, 200% or 300% (default).
Proximity & Ambient Light Sensor parameters
-------------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Proximity Gain: Selection of the gain factor, select from 1x, 2x, 4x (default) or 8x.
* **Proximity Gain**: Selection of the gain factor, select from 1x, 2x, 4x (default) or 8x.
Ambient Light Sensor Gain: Selection of the gain factor, select from 1x, 2x, 4x (default) or 8x.
* **Ambient Light Sensor Gain**: Selection of the gain factor, select from 1x, 2x, 4x (default) or 8x.
Proximity/ALS LED Drive: Selection of the current to drive the Proximity/Ambient Light Sensor IR LED, select from 100 mA (default), 50 mA, 25 mA or 12.5 mA.
* **Proximity/ALS LED Drive**: Selection of the current to drive the Proximity/Ambient Light Sensor IR LED, select from 100 mA (default), 50 mA, 25 mA or 12.5 mA.
R/G/B Colors parameters
-----------------------
^^^^^^^^^^^^^^^^^^^^^^^
Light Sensor Gain: Selection of the gain factor, select from 1x, 2x, 4x (default) or 8x.
* **Light Sensor Gain**: Selection of the gain factor, select from 1x, 2x, 4x (default) or 8x.
Light Sensor LED Drive: Selection of the current to drive the Light Sensor IR LED, select from 100 mA (default), 50 mA, 25 mA or 12.5 mA.
* **Light Sensor LED Drive**: Selection of the current to drive the Light Sensor IR LED, select from 100 mA (default), 50 mA, 25 mA or 12.5 mA.
Supported hardware
------------------
Event generation
^^^^^^^^^^^^^^^^
* **Separate Gesture events**: When enabled will generate a ``<TaskName>#Swipe=<gesture>`` event (see below), independent from **Interval**. This allows gestures to be handled independently from measuring the proximity and ambient light, or R/G/B colors. The ``Gesture`` value will be updated for every gesture detected, but the Values events will only trigger on Interval, if this checkbox is enabled.
Values
^^^^^^
Depending on the **Plugin Mode** setting either the Values are ``Gesture``, ``Proximity`` and ``Light`` or ``R``, ``G`` and ``B``. When not manually changed, they will be switched by the plugin when selecting the other Plugin Mode setting.
.. Supported hardware
.. ^^^^^^^^^^^^^^^^^^
|P064_usedby|
@@ -71,10 +103,10 @@ Supported hardware
.. .. include:: P064_commands.repl
.. Events
.. ~~~~~~
Events
~~~~~~
.. .. include:: P064_events.repl
.. include:: P064_events.repl
Change log
----------
@@ -82,6 +114,9 @@ Change log
.. versionchanged:: 2.0
...
|added| 2024-03-30: Separate Gesture events option.
|added|
Major overhaul for 2.0 release.
docs/source/Plugin/P064_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 63 KiB

docs/source/Plugin/P064_PluginModeOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

docs/source/Plugin/P064_events.repl
+21
View File
@@ -0,0 +1,21 @@
.. csv-table::
:header: "Event", "Example"
:widths: 30, 20
"
``<TaskName>#Swipe,<gesture>``
``<gesture>`` values:
* ``0``: None
* ``1``: Left
* ``2``: Right
* ``3``: Up
* ``4``: Down
* ``5``: Near (towards the sensor)
* ``6``: Far (away from the sensor)
","
Will trigger when the configuration option **Separate Gesture events** is enabled.
These values are the same for the ``Gesture`` value when that is used.
"
docs/source/Plugin/P077_commands.repl
+8
View File
@@ -24,3 +24,11 @@
","
Will reset the calibration values to the default values, causing auto-calibration.
"
"
``cseclearpulses``
","
(Added: 2024-01-16)
Will reset the CF-pulse counter.
N.B. this also clears the kWh counter as it is derived from the CF-pulse counter.
"
docs/source/Plugin/P080.rst
+76 -5
View File
@@ -1,4 +1,4 @@
.. include:: ../Plugin/_plugin_substitutions_p08x.repl
.. include:: ../Plugin/_plugin_substitutions_p08x.repl
.. _P080_page:
|P080_typename|
@@ -24,17 +24,86 @@ Used libraries: |P080_usedlibraries|
Supported hardware
------------------
|P080_usedby|
.. .. |P080_usedby|
.. image:: P080_iButtonReader1.png
:width: 200px
.. image:: P080_iButtonReader2.png
:width: 200px
This type of reader is available at sites like Aliexpress and eBay. The wiring for these units can be somewhat confusing:
.. code-block:: none
ESP iButton (4 wires)
GPIO <--> 1-wire/D (green) with 1k..10k Pull-up to VCC
GND <--> GND (red)
ESP Resistor LED
VCC <--> Anode (black)
GPIO <--> 470 ohm <--> Cathode (white)
The value for the pull-up resistor on the 1-wire GPIO pin depends somewhat, sometimes, 10k doesn't work reliable, especially when using longer wires (> 2m), then lowering to 4k7 or 2k2 usually fixes that. For really problematic installations with high (electrical) noise levels, a 1k resistor may be needed to make it work reliable.
Description
-----------
The iButton, developed by Dallas, now Maxim, is a coded key or button, that can be used for access control or similar identity checks. They use RFID technology to transfer their ID to the receiver, once in close proximity of the receiver.
The iButtons often come in the shape shown in the image below, and can be attached to a keyring for easy access and use.
These buttons are available as read-only iButtons, and as rewritable iButtons, where the user can change the ID of the button. Both types can be read by ESPEasy, but ESPEasy does not provide tools or features to write an ID to the rewritable buttons, separate tools for that can be obtained elsewhere.
.. image:: P080_iButtonExamples.png
:width: 200px
Configuration
-------------
.. image:: P080_DeviceConfiguration.png
:alt: Device 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.
Sensor
^^^^^^
* **GPIO 1-Wire**: The reader only needs a single GPIO pin (and GND) to be connected. The 1-Wire hardware configured in ESPEasy requires a ca. 4k7 ohm (range 1k..10k depending on wire-length) pull-up resistor between VCC (3.3V) and the GPIO pin. Internal pull-up of the ESP is not sufficient!
Any additional wires on the receiver unit mostly are used for indicator leds, that can optionally be controlled using standard GPIO commands from rules. (Don't forget a resistor to limit the current...)
Device Settings
^^^^^^^^^^^^^^^
* **Device Address**: Select the desired device ID that the plugin should respond to. This requires the device to be enabled, and an iButton in contact with the receiver when opening the device settings page! When set, the task will only respond to this iButton ID, when read.
* **Event with iButton address**: With this option enabled, and the **Device Address** selection left to ``- None -``, instead of responding to a single iButton, an event is generated for any iButton that is recognized by the receiver. And once removed, the same event is generated without the iButton address. This can be processed in rules. See below in the **Events** chapter for a more detailed description.
Data Acquisition
^^^^^^^^^^^^^^^^
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.
* **Interval** By default, Interval will be set to 0 sec. as it is optional. It is the frequency used to send the value to any Controllers configured for this device.
Values
^^^^^^
The plugin provides the ``iButton`` value, that shows either 0 (no iButton on the receiver) or 1 (iButton recognized).
.. Commands available
.. ^^^^^^^^^^^^^^^^^^
.. .. include:: P080_commands.repl
.. Events
.. ~~~~~~
Events
~~~~~~
.. .. include:: P080_events.repl
.. include:: P080_events.repl
Change log
----------
@@ -42,6 +111,8 @@ Change log
.. versionchanged:: 2.0
...
|added| 2024-05-10 Support for Event with iButton address.
|added|
Major overhaul for 2.0 release.
docs/source/Plugin/P080_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

docs/source/Plugin/P080_events.repl
+32
View File
@@ -0,0 +1,32 @@
.. csv-table::
:header: "Event", "Example"
:widths: 30, 30
"
``<taskName>#Address=<state>[,<iButtonAddress_high>,<iButtonAddress_low>]``
``<state>``: 0 or 1, depending on wether the iButton is on the receiver (1) or not (0).
``<iButtonAddress_high>``: The high 4 bytes of the (64 bit) iButton address in hexadecimal presentation, with a ``0x`` prefix. The address parts are only included if the iButton is detected by the receiver.
``<iButtonAddress_low>``: The low 4 bytes of the iButton address in hexadecimal presentation.
","
This event is generated when the **Event with iButton address** setting is *enabled*, and no **Device Address** is selected (*None*).
As the iButton address is in fact a 64 bit value (though only 57 bits are used), this value is too large to be stored in a regular variable in the rules, so they are split into 2 parts, as often sets of iButtons are produced in the same batch, where the higher bits are the same, and only the lower bits vary.
These numbers can be processed, f.e. in a lookup table, similar to the example `Validate a RFID tag against a sorted list <../Rules/Rules.html#validate-a-rfid-tag-against-a-sorted-list>`_ (though somewhat different...)
Simply logging the data could look like this:
.. code-block:: none
On iButton#Address Do
Let,1,%eventvalue2%
Let,2,%eventvalue3%
LogEntry,'iButton %eventvalue2%_%eventvalue3% = %eventvalue1% (%v1% / %v2%)'
Endon
"
docs/source/Plugin/P080_iButtonExamples.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 234 KiB

docs/source/Plugin/P080_iButtonReader1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 101 KiB

docs/source/Plugin/P080_iButtonReader2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 78 KiB

docs/source/Plugin/P087.rst
+10 -1
View File
@@ -48,7 +48,7 @@ This section only shows settings when the plugin is configured and enabled.
.. image:: P087_FilteringConfiguration.png
* **RegEx**: Specify a regular expression to apply to the received data before it is accepted as acceptable data.
* **RegEx**: Specify a regular expression to apply to the received data before it is accepted as acceptable data. This regular expression is based on the Lua script language, and is documented here: http://www.lua.org/manual/5.2/manual.html#6.4.1
* **Nr Chars use in RegEx**: Limit the length of the data to be checked using the **RegEx** regular expression filter. When set to 0 all data is checked.
@@ -109,6 +109,13 @@ Commands available
.. include:: P087_commands.repl
Get Config Values
^^^^^^^^^^^^^^^^^
Get Config Values retrieves values or settings from the sensor or 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.
.. include:: P087_config_values.repl
Change log
----------
@@ -116,6 +123,8 @@ Change log
.. versionchanged:: 2.0
...
|added| 2024-02-25 Add support for ``serialproxy_test`` command and retrieving the separate groups from parsed regex.
|added| 2023-03-22 Add support for writing any binary data out via the serial port.
|added| 2020-02-22
docs/source/Plugin/P087_commands.repl
+9
View File
@@ -26,3 +26,12 @@
``'0xXXxx XX,xx-XX:xx'``: A sequence of hexadecimal values (range: 0x00..0xFF), that *can* be separated by a space, comma, dash, colon, semicolon or period, or are just entered adjecent. Only the first 2 characters should be ``0x`` or ``0X``, the rest is interpreted as hex bytes, and appended to the data to send. Quotes are only required if space or comma separators are used.
Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.
"
"
``serialproxy_test,'<content to process>[,...]'``
``<content to process>``: Some text to be processed as if it was received via the serial port.
","
This command is intended for testing the regular expression and filtering.
The sentence provided with this command is handed over for processing as if it was received via the serial port, so it will be processed and filtered, and an event will be generated if it's matched.
"
docs/source/Plugin/P087_config_values.repl
+70
View File
@@ -0,0 +1,70 @@
.. csv-table::
:header: "Config value", "Information"
:widths: 20, 30
"
``[<taskname>#group.<groupnr>]``
","
Get the contents from groupnr after processing received data.
NB: The regular expression parsen uses 0-based group numbers (where most other regex parsers use 1-based group numbers!)
"
"
``[<taskname>#next.<groupvalue>]``
","
Get the value of the next group that holds ``<groupvalue>``.
Example:
Regular expression: ``((node)=(%d+);?)((weight)=(%d+);?)((temp%d?)=(%-?%d+);?)((rssi)=(%-?%d+);?)``
Received data: ``node=1;weight=40;temp1=20;rssi=-30``
This will result in these groups:
.. list-table::
:widths: 20, 50, 200
:header-rows: 1
* - Group
- Data
-
* - 0
- node=1
-
* - 1
- node
-
* - 2
- 1
-
* - 3
- weight=40
-
* - 4
- weight
-
* - 5
- 40
-
* - 6
- temp1=20
-
* - 7
- temp1
-
* - 8
- 20
-
* - 9
- rssi=-30
-
* - 10
- rssi
-
* - 11
- -30
-
Requesting ``[SerialProxy#next.weight]`` will return the value ``40``.
"
docs/source/Plugin/P095.rst
+50 -27
View File
@@ -53,6 +53,7 @@ The text on most displays is somewhat confusing, as not the usual SPI names are
3V3 --- VCC (most displays only support 3.3V)
GND --- GND
MOSI --> SDA/SDI
MISO --> SDO/DO (optional, not used)
CLK --> SCL/SCK
(gpio) --> DC
(gpio) --> CS
@@ -68,23 +69,35 @@ Device configuration
.. image:: P095_DeviceConfiguration.png
:alt: Device configuration
* **Name** A unique name should be entered here.
* **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.
* **Enabled**: The device can be disabled or enabled. When not enabled the device should not use any resources.
Actuator
^^^^^^^^
* **GPIO -> TFT CS** Select the GPIO pin to use for the ``CS`` connection. If the display doesn't have a ``CS`` connection it can be set to *None*.
* **GPIO -> TFT DC** The GPIO pin to use for the ``DC`` connection (Data/Command).
* **GPIO -> TFT RST** Select the GPIO pin to use for the ``RES`` (reset) connection. If the display doesn't have a ``RES`` (or RST) connection, or no free pin is available, it can be set to *None*. If it is set to None, for proper operation it may need too be wired to the Reset connection on the ESP, so the device is initialized correctly.
* **GPIO -> Backlight (optional)** Select the GPIO pin to use for controlling the backlight. To save power, the backlight can be dimmed, or turned off if the display is turned off. If set to *None*, usually the max. brightness is used for the backlight.
* **Backlight percentage** The backlight can be controlled via PWM modulation on the Backlight (BLK) pin of the display. This is set as a percentage between 1 and 100.
* **Display button** A GPIO pin can be configured to wake the display on demand. This, combined with the **Display Timeout** setting, can preserve the lifetime of the display, and save some power.
* **Inversed Logic** When checked, reverses the pin-state action of the **Display button** gpio. This allows an external circuit, f.e. an IR sensor, that may provide a *high* signal when activated, to wake the display.
* **Display Timeout** Select the timeout in seconds to turn off the display after the last update or wake-up. Only used if the **Display button** is *also* configured.
* **TFT Display model** Select the hardware model that is connected. Currently there are only preset resolutions available.
* **Invert display** Default value for Invert display, some displays have foreground and background colors swapped (f.e. M5Stack Core2 using ILI9342C), this option is applied at plugin initialization.
* **GPIO -> TFT CS**: Select the GPIO pin to use for the ``CS`` connection. If the display doesn't have a ``CS`` connection it can be set to *None*.
* **GPIO -> TFT DC**: The GPIO pin to use for the ``DC`` connection (Data/Command).
* **GPIO -> TFT RST**: Select the GPIO pin to use for the ``RES`` (reset) connection. If the display doesn't have a ``RES`` (or RST) connection, or no free pin is available, it can be set to *None*. If it is set to None, for proper operation it may need too be wired to the Reset connection on the ESP, so the device is initialized correctly.
Device Settings
^^^^^^^^^^^^^^^
* **GPIO -> Backlight (optional)**: Select the GPIO pin to use for controlling the backlight. To save power, the backlight can be dimmed, or turned off if the display is turned off. If set to *None*, usually the max. brightness is used for the backlight, but sometimes the BL/LED pin of the display has to be connected to ``VCC`` to get the content visible.
* **Backlight percentage**: The backlight can be controlled via PWM modulation on the Backlight (BLK) pin of the display. This is set as a percentage between 1 and 100.
* **Display button**: A GPIO pin can be configured to wake the display on demand. This, combined with the **Display Timeout** setting, can preserve the lifetime of the display, and save some power.
* **Inversed Logic**: When checked, reverses the pin-state action of the **Display button** gpio. This allows an external circuit, f.e. an IR sensor, that may provide a *high* signal when activated, to wake the display.
* **Display Timeout**: Select the timeout in seconds to turn off the display after the last update or wake-up. Only used if the **Display button** is *also* configured.
* **TFT Display model**: Select the hardware model that is connected. Currently there are only preset resolutions available.
* **Invert display**: Default value for Invert display, some displays have foreground and background colors swapped (f.e. M5Stack Core2 using ILI9342C and some ILI9486/ILI9488 models), this option is applied at plugin initialization.
Available options:
@@ -94,10 +107,12 @@ Available options:
.. warning::
The **ILI9481** display controller does have issues when rotating, by using the ``<trigger>,rot,<n>`` command, to change the display orientation after some content is already displayed on the screen (content may move, rotate and/or mirror unexpectedly). It is advised to clear the screen after changing the rotation setting.
.. note:: ILI9486 displays tested so far (sourced from Aliexpress) either are *compatible* with ILI9488 or **are** ILI9488 displays, that's why they share the same entry in the list. If you find an ILI9486 display that doesn't work with this setting, please raise an issue in ESPEasy Github Issues list, so this can be adjusted.
Layout
^^^^^^^^
* **Rotation** Depending on how the display is to be mounted/installed, it may be needed to rotate the content, or with a non-square resolution, to use the display in *Landscape* layout instead of the default *Portrait*.
* **Rotation**: Depending on how the display is to be mounted/installed, it may be needed to rotate the content, or with a non-square resolution, to use the display in *Landscape* layout instead of the default *Portrait*.
Available options:
@@ -120,13 +135,18 @@ Available options:
Default setting is *Continue to next line*.
* **Font scaling** The scaling factor for the currently active font. Select a factor between 1 and 10.
* **Default font**: If fonts are available in the build (excluded from some builds because of .bin size issues), the default font at initialization can be selected. The names/numbers that can be used in the ``<trigger>,font,<fontname|fontnr>`` are shown in the combobox, and documented below in the **AdafruitGFX_Helper** documentation. The font numbers aren't consecutive if all fonts aren't included, to keep them consistent across builds.
* **Show splash on start** When available, and enabled, will show an ESPEasy & plugin name text-splash during start of the plugin. If also some content is configured, this will be written over the splash, as that is not cleared after being displayed.
.. image:: P095_DefaultFontOptions.png
:alt: Default font
* **Clear display on exit** When checked, will clear the display when the task is disabled, either from settings or via the ``TaskDisable`` command. The screen will be turned off, and when a backlight pin is configured, also the backlight is turned off.
* **Font scaling**: The scaling factor for the currently active font. Select a factor between 1 and 10.
* **Write Command trigger** The command to handle any commands for this device can be selected here. This can make the commands compatible with other (tft) displays, using the same command structure via the ESPEasy Adafruit Graphics helper class.
* **Show splash on start**: When available, and enabled, will show an ESPEasy & plugin name text-splash during start of the plugin. If also some content is configured, this will be written over the splash, as that is not cleared after being displayed.
* **Clear display on exit**: When checked, will clear the display when the task is disabled, either from settings or via the ``TaskDisable`` command. The screen will be turned off, and when a backlight pin is configured, also the backlight is turned off.
* **Write Command trigger**: The command to handle any commands for this device can be selected here. This can make the commands compatible with other (tft) displays, using the same command structure via the ESPEasy Adafruit Graphics helper class.
Available options:
@@ -142,19 +162,20 @@ Available options:
The command is handled non-case sensitive. See below for available commands and subcommands.
* **Wake display on receiving text** When checked, the display will be enabled once any content is written to the screen, either triggered by the Interval, or from a command. Default checked.
* **Wake display on receiving text**: When checked, the display will be enabled once any content is written to the screen, either triggered by the Interval, or from a command. Default checked.
* **Text Coordinates in col/row** When checked, the coordinates for the ``txp``, ``txz`` and ``txtfull`` subcommands will be handled in cursor columns & rows, instead of pixels. Column and row are calculated from the current font size and font scaling settings.
* **Text Coordinates in col/row**: When checked, the coordinates for the ``txp``, ``txz`` and ``txtfull`` subcommands will be handled in cursor columns & rows, instead of pixels. Column and row are calculated from the current font size and font scaling settings.
* **Use -1px offset for txp & txtfull** For backward compatibility with the previous, non-AdafruitGFX_helper based, plugin implementation, that used 0-based coordinates, an offset of -1 pixel can be applied to the ``txp``, ``txz`` and ``txtfull`` subcommands. This option is enabled by default.
* **Use -1px offset for txp & txtfull**: For backward compatibility with the previous, non-AdafruitGFX_helper based, plugin implementation, that used 0-based coordinates, an offset of -1 pixel can be applied to the ``txp``, ``txz`` and ``txtfull`` subcommands. This option is enabled by default.
* **Background-fill for text** When checked, for any text-line sent to the screen, the entire background (including top and bottom lines) will have the provided background color, *unless* transparent is used (Background color == Foreground color). Default checked.
* **Background-fill for text**: When checked, for any text-line sent to the screen, the entire background (including top and bottom lines) will have the provided background color, *unless* transparent is used (Background color == Foreground color). Default checked.
Content
^^^^^^^^
* **Foreground color**
* **Background color**
* **Foreground color**:
* **Background color**:
These are the default colors, used to display the content as configured below (if any). The background color is also used as the Clear screen color.
@@ -166,7 +187,7 @@ Colors can be specified in 3 ways:
If the Foreground and Background colors are the same, the background color will become ``transparent``. If the Forground color is empty, as a default ``white`` will be set.
* **Line 1..24** Predefined content can be specified. The number of lines available depends on the size of the display, the font used, the font scaling that is set and the selected rotation.
* **Line 1..24**: Predefined content can be specified. The number of lines available depends on the size of the display, the font used, the font scaling that is set and the selected rotation.
The usual variables, like ``[Taskname#Valuename]``, or ``%v1%``, system variables, formulas and functions can be used.
@@ -174,14 +195,14 @@ Input length is limited to 60 characters per line. If a longer calculated text i
Next to Line 24, the remaining capacity in characters is displayed.
The total combination of lines * input length can not exceed 1000 characters (sized dynamically), as there is limited storage per task available for these settings. An error message will be shown after (trying to) save the settings, **any excess content will be discarded!**
The total combination of lines * input length can not exceed 5192 characters (1000 on some builds) (sized dynamically), as there is limited storage per task available for these settings. An error message will be shown after (trying to) save the settings, **any excess content will be discarded!**
Example:
.. image:: P095_SaveError.png
:alt: Save error
* **Interval** By default, Interval will be set to 0. If set to a non-zero value, the pre-configured content will be updated automatically using that interval (seconds). Depending on the **Text print Mode** setting, content that may have been draw from rules or external commands, may be erased.
* **Interval**: By default, Interval will be set to 0. If set to a non-zero value, the pre-configured content will be updated automatically using that interval (seconds). Depending on the **Text print Mode** setting, content that may have been draw from rules or external commands, may be erased.
Values
^^^^^^
@@ -209,6 +230,8 @@ Change log
.. versionchanged:: 2.0
...
|added| 2020-04-20 Initially added
|added| 2024-07-07 Add support for ILI9486/ILI9488 displays.
|added| 2022-04-23 Rewrite of the plugin based on AdafruitGFX_helper, udated documentation based on shared settings with :ref:`P116_page` and AdafruitGFX_helper
|added| 2020-04-20 Initially added
docs/source/Plugin/P095_DefaultFontOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

docs/source/Plugin/P095_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 103 KiB

After

Width:  |  Height:  |  Size: 107 KiB

docs/source/Plugin/P095_TFTDisplayModelOptions.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 54 KiB

After

Width:  |  Height:  |  Size: 45 KiB

docs/source/Plugin/P095_commands.repl
+1 -1
View File
@@ -31,7 +31,7 @@
"
| ``tftcmd,clear``
","
| Clear the display, using the default background color.
| Clear the display, using the **default** background color. For clearing with a custom background color see the ``<trigger>,clear[,<color>]`` command.
"
"
| ``tftcmd,backlight,<percentage>``
docs/source/Plugin/P105.rst
+95 -93
View File
@@ -1,93 +1,95 @@
.. include:: ../Plugin/_plugin_substitutions_p10x.repl
.. _P105_page:
|P105_typename|
==================================================
|P105_shortinfo|
Plugin details
--------------
Type: |P105_type|
Name: |P105_name|
Status: |P105_status|
GitHub: |P105_github|_
Maintainer: |P105_maintainer|
Used libraries: |P105_usedlibraries|
Datasheet: |P105_datasheet| |P105_datasheet2| |P105_datasheet3|
Description
-----------
The AHT10/AHT20/AHT21 sensors provide Temperature and Humidity measurements (factory calibrated), via an I2C bus connection.
.. warning::
* The **AHT10** device does sometimes not 'play nice' when there are also other I2C devices on the same bus (many complaints can be found on the internet). NB: This may be hardware-, vendor-, or chip-revision-specific.
Because of this peculiarity, other sensors may be more appropriate, like the AHT20/AHT21 also supported by this plugin, or :ref:`P028_page`, :ref:`P106_page`, :ref:`P014_page`, :ref:`P034_page`, :ref:`P051_page`, :ref:`P068_page` or :ref:`P072_page`.
This plugin tries to avoid such situations (I2C bus lock) by (soft) resetting the sensor if it doesn't respond for some time.
Settings
--------
.. image:: P105_DeviceConfiguration.png
**Name**: The name for this task, should be unique.
**Enabled**: Allows to enable/disable the device.
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. The AHT10 sensor allows to select a secondary address by pulling the AO (sometimes marked as A0) pin to high (3.3V) to select the secondary address. That address should then be selected here too. The AHT20/AHT21 sensors only support a single I2C address, so it will be forced to the default address.
Device Settings
^^^^^^^^^^^^^^^^
If the plugin is configured for **Sensor model** AHT10 and other devices configured in a task use the I2C bus, a warning is displayed (see example below) that combining them with this device may cause issues on the I2C bus, resulting in all I2C devices no longer working as intended. This may occur immediately, or only after some time, like 10 minutes or an hour.
.. image:: P105_DeviceWarning.png
**Sensor model** Selection of the connected type of hardware. (AHT2x sensors have a slightly different intialization.)
Available options:
.. image:: P105_SensorModelOptions.png
**AHT10** This sensor model should better be avoided, as it doesn't always work with other devices on the same I2C bus. Also, the AHT15 can be used, but that has similar issues.
**AHT20** An more modern version of the sensor.
**AHT20** An more modern version of the sensor, very similar to the AHT20, in a more compact chip package.
Data Acquisition
^^^^^^^^^^^^^^^^
This group of settings, **Single event with all values**, **Send to Controller** and **Interval** settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.
**Interval** By default, Interval will be set to 60 sec. It is the frequency used to read sensor values and send these to any Controllers configured for this device.
Values
^^^^^^
The names for the values are initially set to a default name, but can be changed if desired. Also, a formula can be entered to re-calculate the value before display/sending to a controller, and the number of decimals can be changed, for Temperature, usually 1 decimal is enough to be displayed (value will be rounded).
Change log
----------
.. versionchanged:: 2.0
...
|added| 2021-08-01 Moved from ESPEasy PluginPlayground to the main repository.
.. include:: ../Plugin/_plugin_substitutions_p10x.repl
.. _P105_page:
|P105_typename|
==================================================
|P105_shortinfo|
Plugin details
--------------
Type: |P105_type|
Name: |P105_name|
Status: |P105_status|
GitHub: |P105_github|_
Maintainer: |P105_maintainer|
Used libraries: |P105_usedlibraries|
Datasheet: |P105_datasheet| |P105_datasheet2| |P105_datasheet3|
Description
-----------
The AHT10/AHT15/AHT20/AHT21/DHT20/AM2301B sensors provide Temperature and Humidity measurements (factory calibrated), via an I2C bus connection.
.. warning::
* The **AHT10** and **AHT15** devices do sometimes not 'play nice' when there are also other I2C devices on the same bus (many complaints can be found on the internet). NB: This may be hardware-, vendor-, or chip-revision-specific.
Because of this peculiarity, other sensors may be more appropriate, like the AHT20/AHT21 also supported by this plugin, or :ref:`P028_page`, :ref:`P106_page`, :ref:`P014_page`, :ref:`P034_page`, :ref:`P051_page`, :ref:`P068_page` or :ref:`P072_page`.
This plugin tries to avoid such situations (I2C bus lock) by (soft) resetting the sensor if it doesn't respond for some time.
This plugin also supports the **DHT20** and **AM2301B** sensors, as these are just **AHT20** sensors with a specific housing.
Settings
--------
.. image:: P105_DeviceConfiguration.png
* **Name**: The name for this task, should be unique.
* **Enabled**: Allows to enable/disable the device.
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. The AHT10 sensor allows to select a secondary address by pulling the AO (sometimes marked as A0) pin to high (3.3V) to select the secondary address. That address should then be selected here too. The AHT20/AHT21 based sensors only support a single I2C address, so it will be forced to the default address.
Device Settings
^^^^^^^^^^^^^^^^
If the plugin is configured for **Sensor model** AHT1x and other devices configured in a task use the I2C bus, a warning is displayed (see example below) that combining them with this device may cause issues on the I2C bus, resulting in all I2C devices no longer working as intended. This may occur immediately, or only after some time, like 10 minutes or an hour.
.. image:: P105_DeviceWarning.png
* **Sensor model** Selection of the connected type of hardware. (AHT2x based sensors have a slightly different intialization.)
Available options:
.. image:: P105_SensorModelOptions.png
**AHT1x** AHT10/AHT15. These sensor models should better be avoided, as it doesn't always work with other devices on the same I2C bus.
**AHT20** An more modern version of the sensor. Use this option also when connecting a DHT20 or AM2301B sensor.
**AHT21** An more modern version of the sensor, very similar to the AHT20, in a more compact chip package.
Data Acquisition
^^^^^^^^^^^^^^^^
This group of settings, **Single event with all values**, **Send to Controller** and **Interval** settings are standard available configuration items. Send to Controller is only visible when one or more Controllers are configured.
* **Interval** By default, Interval will be set to 60 sec. It is the frequency used to read sensor values and send these to any Controllers configured for this device.
Values
^^^^^^
The names for the values are initially set to a default name, but can be changed if desired. Also, a formula can be entered to re-calculate the value before display/sending to a controller, and the number of decimals can be changed, for Temperature, usually 1 decimal is enough to be displayed (value will be rounded).
Change log
----------
.. versionchanged:: 2.0
...
|added| 2021-08-01 Moved from ESPEasy PluginPlayground to the main repository.
docs/source/Plugin/P105_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 43 KiB

After

Width:  |  Height:  |  Size: 46 KiB

docs/source/Plugin/P105_DeviceWarning.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.0 KiB

After

Width:  |  Height:  |  Size: 4.8 KiB

docs/source/Plugin/P105_SensorModelOptions.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.7 KiB

After

Width:  |  Height:  |  Size: 8.3 KiB

docs/source/Plugin/P110.rst
+100 -88
View File
@@ -1,88 +1,100 @@
.. include:: ../Plugin/_plugin_substitutions_p11x.repl
.. _P110_page:
|P110_typename|
==================================================
|P110_shortinfo|
Plugin details
--------------
Type: |P110_type|
Name: |P110_name|
Status: |P110_status|
GitHub: |P110_github|_
Maintainer: |P110_maintainer|
Used libraries: |P110_usedlibraries|
Description
-----------
This I2C sensor with 2 ranges offers distance measurement based on a Laser Time-of-Flight sensor. Output result is in millimeters.
Configuration
--------------
.. image:: P110_DeviceConfiguration.png
**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. Some boards holding this chip offer an extra connection SDO that can be used to select the address, other boards just allow to select the secondary address and keep that active until the next power-cycle of the sensor.
Device Settings
^^^^^^^^^^^^^^^^
**Timing**: The timing setting of the sensor determines the accuracy of the measurement. There are 3 options available:
.. image:: P110_TimingOptions.png
*Normal* The default value (80 msec.)
*Fast* A faster but less accurate measurement (20 msec.) Can be used with a high speed read interval (1-5 sec).
*Accurate* A slower but far more accurate measurement (320 msec.) For use with a longer read interval setting (30-60 sec).
**Range**: the measuring ranges:
.. image:: P110_RangeOptions.png
*Normal* For measurements in the 0 to 800 millimeter range.
*Long* For measurements in the 0 to 2000 millimeter range (but somewhat less accurate).
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 ``Distance``. A formula can be set to recalculate, f.e. to centimeters using ``%value%/10``. The number of decimals is by default set to 2, but for use with millimeters distance it can be set to 0, as no decimals are provided from the measurement.
.. Events
.. ~~~~~~
.. .. include:: P110_events.repl
Change log
----------
.. versionchanged:: 2.0
...
|added| 2021-02-06 Moved to main repository Plugin 110 from PluginPlayground Plugin 133
|added| 2021-02-06 Refactoring to allow multiple instances of the plugin (when using an I2C multiplexer)
.. include:: ../Plugin/_plugin_substitutions_p11x.repl
.. _P110_page:
|P110_typename|
==================================================
|P110_shortinfo|
Plugin details
--------------
Type: |P110_type|
Name: |P110_name|
Status: |P110_status|
GitHub: |P110_github|_
Maintainer: |P110_maintainer|
Used libraries: |P110_usedlibraries|
Description
-----------
This I2C sensor with 2 ranges offers distance measurement based on a Laser Time-of-Flight sensor. Output result is in millimeters.
Configuration
--------------
.. image:: P110_DeviceConfiguration.png
* **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. Some boards holding this chip offer an extra connection SDO that can be used to select the address, other boards just allow to select the secondary address and keep that active until the next power-cycle of the sensor.
Device Settings
^^^^^^^^^^^^^^^^
* **Timing**: The timing setting of the sensor determines the accuracy of the measurement. There are 3 options available:
.. image:: P110_TimingOptions.png
*Normal* The default value (80 msec.)
*Fast* A faster but less accurate measurement (20 msec.) Can be used with a high speed read interval (1-5 sec).
*Accurate* A slower but far more accurate measurement (320 msec.) For use with a longer read interval setting (30-60 sec).
* **Range**: the measuring ranges:
.. image:: P110_RangeOptions.png
*Normal* For measurements in the 0 to 800 millimeter range.
*Long* For measurements in the 0 to 2000 millimeter range (but somewhat less accurate).
* **Send event when value unchanged**: When checked, will generate events for every **Interval**, when unchecked *and* **Interval** is set to 0, a change in **Distance** will immediately trigger events. (NB: Behavior changed since 2024/04/27, when this option was added)
* **Trigger delta** To avoid triggering many events with only a small difference in distance the 'Trigger delta' option is available. This can be set to only trigger an event when the new distance is at least the delta less or more than the previous measurement.
NB: This setting is ignored if 'Send event when value unchanged' is checked!
n
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.
``Interval`` can now be set to 0, causing events to only be generated when changed, with ``Trigger delta`` calculated in.
Values
^^^^^^
There are 2 values available for this sensor, with the default name ``Distance`` and ``Direction``. A formula can be set to recalculate the distance, f.e. to centimeters using ``%value%/10``. The number of decimals can be set to 0, when using millimeters, as no decimals are provided from the measurement.
Value ``Direction`` holds the direction relative to the *previous* distance value: ``-1`` = smaller distance, ``0`` = unchanged distance, ``1`` = greater distance.
.. Events
.. ~~~~~~
.. .. include:: P110_events.repl
Change log
----------
.. versionchanged:: 2.0
...
|added| 2024-04-27 Add options for ``Send event when value unchanged`` and ``Trigger delta``, causing somewhat changed behavior.
|added| 2021-02-06 Moved to main repository Plugin 110 from PluginPlayground Plugin 133
|added| 2021-02-06 Refactoring to allow multiple instances of the plugin (when using an I2C multiplexer)
docs/source/Plugin/P110_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 49 KiB

docs/source/Plugin/P110_RangeOptions.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.0 KiB

After

Width:  |  Height:  |  Size: 16 KiB

docs/source/Plugin/P110_TimingOptions.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.9 KiB

After

Width:  |  Height:  |  Size: 10 KiB

docs/source/Plugin/P113.rst
+109 -104
View File
@@ -1,104 +1,109 @@
.. include:: ../Plugin/_plugin_substitutions_p11x.repl
.. _P113_page:
|P113_typename|
==================================================
|P113_shortinfo|
Plugin details
--------------
Type: |P113_type|
Name: |P113_name|
Status: |P113_status|
GitHub: |P113_github|_
Maintainer: |P113_maintainer|
Used libraries: |P113_usedlibraries|
Description
-----------
This I2C sensor with 2 ranges offers distance measurement based on a Laser Time-of-Flight sensor. Output result for Distance is in millimeters.
The VL53L1X sensor can measure either 0 - 130cm (Normal range) or 0 - 400cm (Long range), where the closely related VL53L0X can measure up to 200cm. The API's for these sensors are not compatible, so different libraries are used.
Configuration
--------------
.. image:: P113_DeviceConfiguration.png
**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. Because of an issue with changing the I2C address of the sensor, this list is limited to 1 item, and the address isn't changed/set.
Device Settings
^^^^^^^^^^^^^^^^
**Timing**: The timing setting of the sensor determines the accuracy of the measurement. There are 6 options available:
.. image:: P113_TimingOptions.png
*100 ms (Normal)* The default value, using an integration time of 100 msec.
*20ms (Fastest)* The fastest but least accurate measurement. Should only be used for Normal range (see below).
*33ms (Fast)* A fast but not very accurate measurement.
*50ms* A somewhat more accurate measurement.
*200ms Accurate* A slower but far more accurate measurement. For use with a longer read interval setting (30-60 sec).
*500ms* The longest integration time available. For use with long read interval settings.
**Range**: the measuring ranges:
.. image:: P113_RangeOptions.png
*Normal (~130cm)* For measurements in the 0 to 1300 millimeter (130cm) range.
*Long (~400cm)* For measurements in the 0 to 4000 millimeter (400cm) range (but somewhat less accurate).
**Send event when value unchanged** To avoid many of the same events when the measurement is stable, this option is off by default. When enabled, every measurement will cause an event, and send the data to any enabled Controller.
**Trigger delta** To avoid triggering many events with only a small difference in distance the 'Trigger delta' option is available. This can be set to only trigger an event when the new distance is at least the delta less or more than the previous measurement.
NB: This setting is ignored if 'Send event when value unchanged' is checked!
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.
**Interval** By default, Interval will be set to 60 sec. Setting this to 1 or 2 seconds, usually offers a reasonable response time.
Values
^^^^^^
The measured distance is available in ``Distance``. A formula can be set to recalculate, f.e. to centimeters using ``%value%/10``. The number of decimals is by default set to 2, but for use with millimeters distance it can be set to 0, as no decimals are provided from the measurement.
The Ambient lighting condition during measurement is available in ``Ambient``. The unit is kcps (Photons per second, recalculated to kilo count per second)
.. Events
.. ~~~~~~
.. .. include:: P113_events.repl
Change log
----------
.. versionchanged:: 2.0
|added| 2021-04-05 Added to main repository as Plugin 113 Distance - VL53L1X (400cm), based on a copy of Plugin 110 Distance - VL53L0X (200cm)
.. include:: ../Plugin/_plugin_substitutions_p11x.repl
.. _P113_page:
|P113_typename|
==================================================
|P113_shortinfo|
Plugin details
--------------
Type: |P113_type|
Name: |P113_name|
Status: |P113_status|
GitHub: |P113_github|_
Maintainer: |P113_maintainer|
Used libraries: |P113_usedlibraries|
Description
-----------
This I2C sensor with 2 ranges offers distance measurement based on a Laser Time-of-Flight sensor. Output result for Distance is in millimeters.
The VL53L1X sensor can measure either 0 - 130cm (Normal range) or 0 - 400cm (Long range), where the closely related VL53L0X can measure up to 200cm. The API's for these sensors are not compatible, so different libraries are used.
Configuration
--------------
.. image:: P113_DeviceConfiguration.png
* **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. Because of an issue with changing the I2C address of the sensor, this list is limited to 1 item, and the address isn't changed/set.
Device Settings
^^^^^^^^^^^^^^^^
* **Timing**: The timing setting of the sensor determines the accuracy of the measurement. There are 6 options available:
.. image:: P113_TimingOptions.png
*100 ms (Normal)* The default value, using an integration time of 100 msec.
*20ms (Fastest)* The fastest but least accurate measurement. Should only be used for Normal range (see below).
*33ms (Fast)* A fast but not very accurate measurement.
*50ms* A somewhat more accurate measurement.
*200ms Accurate* A slower but far more accurate measurement. For use with a longer read interval setting (30-60 sec).
*500ms* The longest integration time available. For use with long read interval settings.
* **Range**: the measuring ranges:
.. image:: P113_RangeOptions.png
*Normal (~130cm)* For measurements in the 0 to 1300 millimeter (130cm) range.
*Long (~400cm)* For measurements in the 0 to 4000 millimeter (400cm) range (but somewhat less accurate).
* **Send event when value unchanged** To avoid many of the same events when the measurement is stable, this option is off by default. When enabled, every measurement will cause an event, and send the data to any enabled Controller.
* **Trigger delta** To avoid triggering many events with only a small difference in distance the 'Trigger delta' option is available. This can be set to only trigger an event when the new distance is at least the delta less or more than the previous measurement.
NB: This setting is ignored if 'Send event when value unchanged' is checked!
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.
* **Interval** By default, Interval will be set to 60 sec. Setting this to 1 or 2 seconds, usually offers a reasonable response time.
Values
^^^^^^
The measured distance is available in ``Distance``. A formula can be set to recalculate, f.e. to centimeters using ``%value%/10``. The number of decimals can be set to 0, when using millimeters, as no decimals are provided from the measurement.
The Ambient lighting condition during measurement is available in ``Ambient``. The unit is kcps (Photons per second, recalculated to kilo count per second)
Value ``Direction`` holds the direction relative to the *previous* distance value: ``-1`` = smaller distance, ``0`` = unchanged distance, ``1`` = greater distance.
.. Events
.. ~~~~~~
.. .. include:: P113_events.repl
Change log
----------
.. versionchanged:: 2.0
...
|added| 2024-04-27 Add value ``Direction``.
|added| 2021-04-05 Added to main repository as Plugin 113 Distance - VL53L1X (400cm), based on a copy of Plugin 110 Distance - VL53L0X (200cm)
docs/source/Plugin/P113_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 50 KiB

docs/source/Plugin/P113_RangeOptions.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.9 KiB

After

Width:  |  Height:  |  Size: 17 KiB

docs/source/Plugin/P113_TimingOptions.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 28 KiB

docs/source/Plugin/P116.rst
+6 -1
View File
@@ -28,7 +28,7 @@ The ST7735, ST7789 and ST7796 chip families drive color TFT displays in various
This plugin supports these display models:
* **ST7735** with resolutions 128 x 128, 128 x 160 and 80 x 160 pixels
* **ST7735** with resolutions 128 x 128, 128 x 160, 80 x 160 and 135 x 240 pixels
* **ST7789** with resolutions 240 x 320, 240 x 240, 240 x 280 and 135 x 240 pixels
* **ST7796** with resolution of 320 x 480 pixels.
@@ -140,6 +140,7 @@ Available options:
* *ST7735 128 x 160px* Allows 16 lines of text in the smallest font scaling setting.
* *ST7735 80 x 160px* Allows 16 lines of text in the smallest font scaling setting.
* *ST7735 80 x 160px (Color inverted)* Special color inverted configuration as used in f.e. M5Stack StickC.
* *ST7735 135 x 240px* Added to support a revision of the TTGO T-Display 16MB Flash module, that won't work with the ST7789 driver, the seller is claiming to use, but does work with this specially crafted ST7735 driver.
* *ST7789 240 x 320px* Allows 32 lines of text in the smallest font scaling setting. Predefined text only goes to 24, extra lines can be displayed from rules or external commands.
* *ST7789 240 x 240px* Allows 24 lines of text in the smallest font scaling setting.
* *ST7789 240 x 280px* Allows 28 lines of text in the smallest font scaling setting. Predefined text only goes to 24, extra lines can be displayed from rules or external commands.
@@ -260,6 +261,10 @@ Change log
.. versionadded:: 2.0
...
|added| 2024-03-26 Add support for ST7735, 135x240 resolution
|added| 2022-07-06 Add support for ST7735 (Color inverted), for M5StickC support
|added| 2021-11-06 Add support for ST7796 displays
|added| 2021-08 Moved from an external forum to ESPEasy.
docs/source/Plugin/P116_TFTDisplayModelOptions.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 35 KiB

After

Width:  |  Height:  |  Size: 44 KiB

docs/source/Plugin/P116_commands.repl
+1 -1
View File
@@ -28,7 +28,7 @@
"
| ``st77xxcmd,clear``
","
| Clear the display, using the default background color.
| Clear the display, using the **default** background color. For clearing with a custom background color see the ``<trigger>,clear[,<color>]`` command.
"
"
| ``st77xxcmd,backlight,<percentage>``
docs/source/Plugin/P123.rst
+110
View File
@@ -0,0 +1,110 @@
.. include:: ../Plugin/_plugin_substitutions_p12x.repl
.. _P123_page:
|P123_typename|
==================================================
|P123_shortinfo|
Plugin details
--------------
Type: |P123_type|
Name: |P123_name|
Status: |P123_status|
GitHub: |P123_github|_
Maintainer: |P123_maintainer|
Used libraries: |P123_usedlibraries|
Supported hardware
------------------
Some displays are available with a touch overlay mounted on top of the visible side of the display. There's a choice of resistive and capacitive touch overlays. The I2C touch overlays supported in this plugin are of the Capacitive kind, being very easy to interact with, comparable to modern smartphones, where you can use a finger for the interaction. (Resistive touch overlays usually require a special pen to be used, or pressed with a finger-nail, to get a response.)
The supported touch overlays (or touch screens), can be found on several displays, f.e. some M5Stack devices, the WT32-SC01 display unit and the LilyGO LILY Pi ESP32 unit.
Device configuration
--------------------
.. image:: P123_DeviceConfiguration.png
* **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 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`
Device Settings
^^^^^^^^^^^^^^^
* **Display task**: Select the display task the touch screen is mounted on. By default, the current task is selected (and ignored), as any other guess would be wrong, and there is no 'None' selection available.
When choosing the correct task, the current display resolution, color depth and rotation settings are tried to be fetched from that task, and copied here in the matching settings. If no settings can be obtained, defaults will be applied.
The configured display will be used to draw the objects, if any, that can be configured below, on.
* **Screen Width (px) (x)**: Width of the display, the (horizontal) ``x`` coordinate, in pixels.
* **Screen Height (px) (y)**: Height of the display, the (vertical) ``y`` coordinate, in pixels. Top/Left coordinate is 0,0.
* **Rotation**: The rotation setting should match the rotation setting of the display, and can be selected as Normal (0), +90, +180 or +270 degrees.
* **Display Color-depth**: If the display settings have been retrieved successfully, this setting can not be changed, but will be used from the display. This value is used to select the correct color mappings for displaying the Objects.
* **Touch minimum pressure**: This setting determines the relative pressure or sensitivity of the FT62x6 touch displays. Lower values make it more sensitive. The range is 0 to 255. Only applicable for the FT62x6 controller.
* **Touchscreen Type (Address)**: Select the type of touchscreen installed, available options:
.. image:: P123_TouchscreenTypeOptions.png
* *FT62x6 (0x38)*: Focaltech FT62x6/FT63x6/FT52x6 touchscreen controller family. Default selection.
* *GT911 (0x5D)*: GT911 touchscreen controller, default address.
* *GT911 (0x14)*: GT911 touchscreen controller, alternate address.
* *CST820 (0x15)*: CST816/CST820 touchscreen controller family.
* *CST226 (0x5A)*: CST226 touchscreen controller. (Not yet tested on real hardware)
* *AXS15231 (0x3B)*: AXS15231 touchscreen controller. (Not yet tested on real hardware)
* *CHSC5816 (0x2E)*: CHSC5816 touchscreen controller. (Not yet tested on real hardware)
* *Auto-detect*: Select this option to have the plugin auto-detect the used touchscreen controller. This auto-detect is mostly based on an I2C device being available at the shown addresses, so might get confused if a non-touchscreen I2C device at one of these addresses is installed.
|
* **Interrupt pin**: Select the GPIO that is connected to the IRQ connection of a GT911 touchscreen controller. The IRQ pin is only used for detection & address configuration, combined with the **Reset pin**, if available and configured. Only used for GT911 controller.
* **Reset pin**: Select the GPIO that is connected to the Reset connection of the touchscreen controller. When set, this will be used to reset the controller during initialization. (See the Warning below). Do not set this GPIO setting if the RST pin is shared with another device, like on a WT32 SC01 Plus, where the display and touch controllers use the same GPIO pin. **Only** set the RST pin on the display configuration, and give that Display task a **lower task number** than the touch screen, as the touchscreen task will try to display defined objects on the connected Display device!
.. note:: The **Interrupt** and **Reset** GPIO pins are optional. Interrupt is only used by the GT911 controller during initialization.
.. warning:: Some devices that have the reset pin connected, initially set that GPIO to low/0, causing the touch controller not to start, and it won't even show up on the I2C Scan. This can be solved by setting the involved GPIO pin to **Output High** on the :ref:`Hardware_page`.
.. warning:: During testing we found that specifically the CST816 touchscreen controller, whiel working as expected, **doesn't** show up in an I2C Scan. This also implies they can't be auto-detected, and have to be set explicitly.
.. include:: Touch_Configuration.repl
Change log
----------
.. versionadded:: 2.0
...
|added| 2024-06-05 Initial release version.
docs/source/Plugin/P123_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

docs/source/Plugin/P123_TouchscreenTypeOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

docs/source/Plugin/P131.rst
+8
View File
@@ -193,6 +193,14 @@ Default setting is *Continue to next line*.
* **Maximum allowed brightness**: The brightness that is the maximum it can be set to, either from UI or via the ``brightness`` command, to optionally help protect both the eyes and the power-supply powering the display. Default is 255. Range: 1..255.
* **Default font**: Select from the currently available fonts, the font that will be active when the plugin is started.
Available fonts are depending on the build used, some builds don't show this option, as then only the ``default`` font is included:
.. image:: P131_DefaultFontOptions.png
The complete list of possible fonts is available at the ``font`` subcommand, below. (This screenshot is taken from a MAX build)
* **Font scaling** The scaling factor for the currently active font. Select a factor between 1 and 4.
* **Clear display on exit** When checked, will clear the display when the task is disabled, either from settings or via the ``TaskDisable`` command. This will fill the display with black pixels, turning all NeoPixels off.
docs/source/Plugin/P131_DefaultFontOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 76 KiB

docs/source/Plugin/P131_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 72 KiB

After

Width:  |  Height:  |  Size: 74 KiB

docs/source/Plugin/P162.rst
+96
View File
@@ -0,0 +1,96 @@
.. include:: ../Plugin/_plugin_substitutions_p16x.repl
.. _P162_page:
|P162_typename|
==================================================
|P162_shortinfo|
Plugin details
--------------
Type: |P162_type|
Name: |P162_name|
Status: |P162_status|
GitHub: |P162_github|_
Maintainer: |P162_maintainer|
Used libraries: |P162_usedlibraries|
Description
-----------
The MCP42xxx/MCP41xxx (the xxx specifies the max resistance value) are dual/single digital potentiometers (digipot), that can be controlled via SPI, and offer a 256 step resolution.
NB: The daisy-chain feature, available in the MCP42xxx chips, is not implemented in this plugin.
Hardware
--------
This plugin is built and tested using a DFRobot `DFR0520 Dual Digipot board <https://wiki.dfrobot.com/Dual_Digital_Pot__100K__SKU__DFR0520>`_ where also a suggestion for wiring up the board is shown.
The board will tolerate 5V power and signals, but when powering the board at 5V and connecting to an ESP, the signal levels **must** be adjusted to 3.3V by using a level converter, to avoid damaging the ESP!
Configuration
-------------
.. image:: P162_DeviceConfiguration.png
* **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.
Sensor
^^^^^^
* **GPIO -> CS PIN**: Configuring the ``CS`` (Chip select) pin is required to correctly address the board, and start the plugin. Also, the standard SPI interface pins ``MOSI`` and ``CLK`` have to be configured and connected.
* **GPIO -> RST PIN (optional)**: Not all boards have the ``RST`` (Reset) pin of the chip available. When not available or not used, it should be set to *- None -*. This pin is not available on the MCP41xxx chips.
* **GPIO -> SHDN PIN (optional)**: Not all boards have the ``SHDN`` (Shutdown) pin of the chip available. When not available or not used, it should be set to *- None -* (Shutdown is explained below). This pin is not available on the MCP41xxx chips.
Device Settings
^^^^^^^^^^^^^^^
* **Initial value Wx**: Range: 0..255. Set the value of the wiper (W) after initialization. By default it is set at the center of the range, 128, corresponding to the value after power-on or reset. Lower values bring the wiper closer to PBx, and higher values closer to PAx level.
* **Initial shutdown Wx**: The wiper can be initially set to Shutdown mode, where the PAx connection is disconnected, and Wx is connected to PBx. When both outputs are initially set to Shutdown, and the SHDN pin is configured, that pin will be used to shutdown the chip. Shutdown mode is undone by setting a value to one of the outputs, using the command described below.
These settings are available for both W0 and W1. NB: The W1 settings can't be applied on the MCP41xxx chips, as that has only 1 digipot.
* **Value at Shutdown**: Range -1..256. Value for the output variables when Shutdown mode for that output is set.
* **Send values on change**: When checked, and Interval set to 0, events will only be generated, and sent to any configured Controllers, when a Value is changed. On startup, the initial values will be sent out, but that's the default behavior for ESPEasy.
Data Acquisition
^^^^^^^^^^^^^^^^
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.
* **Interval** By default, Interval will not be set. The values will be optionally sent to any configured controllers using the interval, when set.
Values
^^^^^^
The plugin provides the ``W0`` and ``W1`` values. A formula can be set to recalculate. The number of decimals can be set as desired, and defaults to 0, as these can only be set to integer values, but a formula could result in decimal values.
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>`
Commands available
^^^^^^^^^^^^^^^^^^
.. include:: P162_commands.repl
Change log
----------
.. versionchanged:: 2.0
...
|added| 2024-04-15 Initial release version.
docs/source/Plugin/P162_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 52 KiB

docs/source/Plugin/P162_commands.repl
+43
View File
@@ -0,0 +1,43 @@
.. csv-table::
:header: "Command Syntax", "Extra information"
:widths: 20, 30
"
``digipot,reset``
","
Sending this command to the task the digipot will be reset to the default wiper settings (128). When a ``RST`` pin is configured, that will be shortly pulled to GND to reset the hardware, else the initial settings will be set to the chip.
On reset, the Initial Shutdown settings will *not* be applied!
"
"
``digipot,shutdown[,<wiper>]``
``<wiper>``: Optional wiper to shutdown.
``0`` = W0
``1`` = W1
``2`` = Both wipers (default when ommitted)
","
This command will set the indicated wiper to Shutdown mode. When no wiper is given, then both wipers will be set to shutdown mode, optionally using the hardware ``SHDN`` pin if that's configured.
Shutdown mode will be released when a value is set to a wiper.
"
"
``digipot,<wiper>,<value>``
``<wiper>``: Wiper to set the value for.
``0`` = W0
``1`` = W1
``2`` = Both wipers
``<value>``: Range 0..255 to set the wiper to.
","
This command will set the provided value to the indicated wiper. When using wiper 2 (both), then a single command will change both values at the same moment.
When setting a value to a wiper, it will also release the shutdown mode, when enabled.
"
docs/source/Plugin/P164.rst
+117
View File
@@ -0,0 +1,117 @@
.. include:: ../Plugin/_plugin_substitutions_p16x.repl
.. _P164_page:
|P164_typename|
==================================================
|P164_shortinfo|
Plugin details
--------------
Type: |P164_type|
Name: |P164_name|
Status: |P164_status|
GitHub: |P164_github|_
Maintainer: |P164_maintainer|
Used libraries: |P164_usedlibraries|
Description
-----------
Sciosense ENS160 and its successor ENS161 are multi-gas sensors based on metal oxide (MOX) technology. They can detect multiple VOCs including ethanol, toluene, hydrogen and oxidizing gases.
The sensors are connected to the I2C bus and provide preprocessed data as TVOC and eCO2 values. See https://www.sciosense.com/ens16x-digital-metal-oxide-multi-gas-sensor-family/ for details about the device.
Hardware
--------
Various boards with the ENS160 are available through electronics market places like Aliexpress. A popular board contains both ENS160 and AHT21 on a single PCB. The AHT21 can be used for temperature compensation as provided by this plugin.
.. image:: P164_board.jpg
Configuration
-------------
.. image:: P164_DeviceConfiguration.png
* **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
^^^^^^^^^^^
* **I2C Address**: The sensor supports two addresses. The actual address depends on the voltage on the ADDR pin of the device.
.. csv-table::
:header: "Address", "Remark"
:widths: 10, 50
"0x52", "Connect ADDR GND"
"0x53", "Connect ADDR to VDD (default on most boards)"
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`
The chip supports both SPI and I2C. The plugin only support I2C using the following pins:
* 1 SDA: Data [MOSI/SDA]
* 2 SCL: Serial Clock [SCLK/SCL]
* 3 ADDR: Address [MISO/ADDR]
* 6 INTn: Interrupt [INTn]
* 7 CSn: SPI interface select, low-> SPI, high->I2C [CSn]
For this plugin the CSn must be wired to VDD to enable the I2C protocol.
On boards sold online, SDO and SDI are often already pulled-up, setting the default I2C address to 0x53.
Device Settings
^^^^^^^^^^^^^^^
* **Detected Sensor Type**: Shows either ``ENS160`` or ``ENS161`` or a number if no sensor or an unknown sensor ID is detected. It will also show the firmware version read from the device if the data is available.
* **Temperature Task**: Task (plugin) providing the temperature compensation
* **Temperature Value**: Value for the temperature compensation
* **Humidity Task**: Task (plugin) providing the humidity compensation
* **Humidity Value**: Value for the humidity compensation
The ENS16x provides temperature and humidity compensation. The plugin must provide the actual temperature and humidity to the device to enable this compensation. For this the plugin needs to read these values from other tasks.
Using the **Temperature Task** and **Temperature Value** the task and value for the Temperature compensation can be selected. Compensation can be switched off by selecting **Not Set**.
Using the **Humidity Task** and **Humidity Value** the task and value for the Humidity compensation can be selected. Compensation can be switched off by selecting **Not Set**.
Note that if either one of the tasks is set to **Not Set** compensation is switched off and a default value is used.
The ENS160 is sold on popular websites on a board including the AHT21 temperature and humidity sensor. This sensor can be used for the compensation algorithm of the ENS160.
Data Acquisition
^^^^^^^^^^^^^^^^
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.
* **Interval** By default, Interval will be set to 60 sec. The data will be collected and optionally sent to any configured controllers using this interval. If the Interval is set lower or equal than the required 10 * Heater time, the plugin will not start!
Values
^^^^^^
The plugin provides the ``TVOC`` and ``eCO2`` values. A formula can be set to recalculate. The number of decimals can be set as desired, and defaults to 2.
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>`
Currently the extra features offered by the sensor are not configurable in this plugin.
These may be added later.
Change log
----------
.. versionchanged:: 2.0
...
|added|
2023-12-27 Initial release version.
docs/source/Plugin/P164_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 68 KiB

docs/source/Plugin/P164_board.jpg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 93 KiB

docs/source/Plugin/P166.rst
+117
View File
@@ -0,0 +1,117 @@
.. include:: ../Plugin/_plugin_substitutions_p16x.repl
.. _P166_page:
|P166_typename|
==================================================
|P166_shortinfo|
Plugin details
--------------
Type: |P166_type|
Name: |P166_name|
Status: |P166_status|
GitHub: |P166_github|_
Maintainer: |P166_maintainer|
Used libraries: |P166_usedlibraries|
Description
-----------
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.
.. image:: P166_DFRobot_GP8403_board.png
(Image (c) DFRobot)
Configuration
-------------
.. image:: P166_DeviceConfiguration.png
* **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
^^^^^^^^^^^
* **I2C Address**: The device supports 8 addresses, and by default comes configured for address ``0x5F``, as reflected in the available options:
.. image:: P166_I2CAddressOptions.png
Available addresses are in the range ``0x58`` to ``0x5F``.
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`
Device Settings
^^^^^^^^^^^^^^^
* **Output range**: Select the desired output voltage range:
.. image:: P166_OutputRangeOptions.png
Available options:
* *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.
* *0-10V*: (Preconfigured default) The maximum available voltage is 10V.
The DAC does not support a different output range setting per output.
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.
* **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.
* **Initial value output 0**:
* **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!
Preset values
^^^^^^^^^^^^^
* **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.
When leaving the *Name* field empty, that preset will not be saved, thus effectively deleted from the list.
Data Acquisition
^^^^^^^^^^^^^^^^
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.
* **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).
Values
^^^^^^
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.
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>`
Commands available
^^^^^^^^^^^^^^^^^^
.. include:: P166_commands.repl
Get Config Values
^^^^^^^^^^^^^^^^^
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.
.. include:: P166_config_values.repl
Change log
----------
.. versionchanged:: 2.0
...
|added|
2024-01-30 Initial release version.
docs/source/Plugin/P166_DFRobot_GP8403_board.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 71 KiB

docs/source/Plugin/P166_DeviceConfiguration.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

docs/source/Plugin/P166_I2CAddressOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

docs/source/Plugin/P166_OutputRangeOptions.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

docs/source/Plugin/P166_commands.repl
+40
View File
@@ -0,0 +1,40 @@
.. csv-table::
:header: "Command Syntax", "Extra information"
:widths: 20, 30
"
``<ch>`` = Output channel, 0, 1 or 2 (both channels)
","
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).
"
"
``gp8403,volt,<ch>,<value>``
","
Set the output value for the channel(s) in volt. The range is determined by the configured Output range setting.
"
"
``gp8403,mvolt,<ch>,<value>``
","
Set the output value for the channel(s) in milli volt. The range is determined by the configured Output range setting.
"
"
``gp8403,range,<5|10>``
","
Set the output range to either 5 (0-5V) or 10 (0-10V). Is also set to the Device configuration, but not saved.
The range is applied to both channels, no separate configuration per channel supported by the chip.
"
"
``gp8403,preset,<ch>,<name>``
","
Set the output value for the channel(s) to the value configured for the preset stored with ``<name>``.
The value is range-checked before it is applied, so when configured for Output range 0-5V, a preset of 7V will be ignored.
When using duplicate names, the first matched preset will be used.
"
"
``gp8403,init,<ch>``
","
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.
"
docs/source/Plugin/P166_config_values.repl
+24
View File
@@ -0,0 +1,24 @@
.. csv-table::
:header: "Config value", "Information"
:widths: 20, 30
"
``[<taskname>#preset<X>]``
","
Returns the numbered preset value ``<X>``, range ``preset1``..``preset25``, as shown in the configuration. Only configured values, having a name, can be retrieved.
"
"
``[<taskname>#initial0]``
","
Returns the configured initial voltage for output 0.
"
"
``[<taskname>#initial1]``
","
Returns the configured initial voltage for output 1.
"
"
``[<taskname>#range]``
","
Returns the configured Output range value 5 (0-5V) or 10 (0-10V)
"

Some files were not shown because too many files have changed in this diff Show More