diff --git a/docs/source/Participate/PlatformIO.rst b/docs/source/Participate/PlatformIO.rst index 3952252185..eb32add3ce 100644 --- a/docs/source/Participate/PlatformIO.rst +++ b/docs/source/Participate/PlatformIO.rst @@ -6,7 +6,7 @@ PlatformIO ESP easy can be built using the Arduino IDE or PlatformIO (PIO). Arduino IDE is not being used during development, so it may take some more effort to get it setup for building ESPeasy. -We advice to use PlatformIO as build environment. +We *strongly* advise to use PlatformIO as build environment. PlatformIO is just the build, test and upload environment for many micro controllers like the ESP8266 and ESP32 we use. @@ -68,6 +68,7 @@ For development of ESPEasy, a number of extensions has to be installed in VS-Cod * PlatformIO IDE (by PlatformIO) * C/C++ IntelliSense (by Microsoft) +* C/C++ Extension Pack (by Microsoft) * Uncrustify (by Zachary Flower, originally by Laurent Tréguier) Optional, but highly recommended: @@ -81,6 +82,7 @@ Optional, but highly recommended: * reStructuredText Syntax highlighting (by Trond Snekvik) * Extension pack for reStructuredText (by LeXtudio Inc.) * Markdown All in One (by Yu Zhang) +* WSL (by Microsoft) (when using WSL2 as documented below) Uncrustify @@ -92,6 +94,8 @@ For new code contributions, it is highly appreciated if the code is formatted us NB: Uncrustify has to be installed separately, as it is not included in the plugin! Download `Uncrustify from Sourceforge.net `_ +When using a Linux OS, f.e. WSL with Ubuntu, uncrustify can be installed via the regular package manager (shown below). It is strongly advised to use version 0.78 or newer, as older versions seem to have some bugs, causing document formatting to fail. + To do so: * Right click mouse in editor @@ -176,10 +180,66 @@ All these mainly apply to the latest ESP32-xx builds using ESP-IDF5.x. On a beefy desktop PC, like an AMD Ryzen9 with 12 CPU cores, building a ``MAX`` build for ESP32-S3 takes about 10 - 15 minutes on Windows. The same build when using WSL2 via VS-Code takes only 2 minutes to build. +When using VS-Code with WSL2, the VS-Code editor application runs on Windows, and, via the WSL plugin, communicates with a VS-Code server component on a Linux instance, running on WSL, that has the source code repository available, and where the build process is executed. + Installing WSL2 --------------- +For installing WSL2 the following steps are needed. Assumption here is that the default Linux distribution for WSL is used, currently Ubuntu (24.04 LTS), using apt-get as the package manager. Other Linux distributions may use a different package manager, like dnf, zypper or yum, using somewhat different commands. Those commands are not documented here. + +Install WSL2 - The Windows part +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Open a Windows Command prompt, preferrably Powershell, with Administrator privileges (Press the Windows key and start typing ``powershell``, then select Run as administrator) + +* Type the command ``wsl --install`` and press , this will start the installation procedure, ask for permissions via User Account Control where needed (that must be confirmed), and download and install what's required. + +* Once this part of the installation is complete, the computer must be restarted. This will install any additional Windows components that weren't installed yet. + +* After logging in to Windows, the installation procedure will be further completed, and you will be asked to enter a username and password for your day-to-day Linux user. This password will be needed later, f.e. when starting the WSL Linux instance, so best practice is to store it in a password safe of some sort (or write it on a Post-It note and stick that under your keyboard ;-)) + +Install WSL2 - The Linux part +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Now that Linux is installed, it's strongly advised to get it up to date with the latest patches, similar to Windows Update. This should be repeated on a regular basis to keep your installation up to date: + +.. highlight::sh + +.. code-block:: + + sudo apt-get update + sudo apt-get upgrade + +NB: The ``sudo`` command will ask for your current account password once, (and maybe later again after some time has passed). When asked for confirmation, confirm the installation of any needed updates, or add the ``-y`` parameter to the ``upgrade`` command to continue without questions. + +Additionally some tools need to be installed so PlatformIO can be properly installed later, and we can use the Uncrustify plugin in VS-Code to format the code nicely: + +.. highlight::sh + +.. code-block:: + + sudo apt-get install python3-venv python3-pip uncrustify + +NB: When running an older release of Ubuntu, like 2022.04 LTS, then uncrustify needs to be install/updated manually with a newer version, as the distributed version isn't working correctly. Or your Ubuntu install could be upgraded to 2024.04 (or newer) to correct this issue. + +Once this is completed, you can get the ESPEasy code in your WSL Linux file system. By default your Linux instance has access to the same internet connection as the host-computer that's running WSL, so the commands are the same as below for cloning a repository (**Clone your forked repositoryto your computer**) + +Start VS-Code from Linux +^^^^^^^^^^^^^^^^^^^^^^^^ + +Now that the repository is available locally, you can start VS-Code from the root folder of this repository: + +.. highlight::sh + +.. code-block:: + + cd ESPEasy + code . + +This will install, or update, the VS-Code server component in Linux and then open the VS-Code IDE in your Windows environment, assuming you have installed the suggested WSL plugin in VS-Code. + + Linking USB serial adapter to WSL2 ---------------------------------- @@ -190,7 +250,7 @@ After the USB device is 'bound' (shared), it must be attached to a specific wsl N.B. this must be repeated after a device was unplugged and replugged. The required steps are described `here `_ -However since this is rather tedious and error prone, it is strongly adviced to use a GUI tool like `WSL USB Manager `_ to perform these steps. +However since this is rather tedious and error prone, it is strongly advised to use a GUI tool like `WSL USB Manager `_ to perform these steps. After attaching an USB device to a WSL instance, it is best to check whether it was found using `dmesg` via the command line on WSL2. @@ -201,7 +261,7 @@ If only an USB device was detected but no `/dev/ttyUSBxx` was assigned, then a m * ``sudo modprobe cp210x`` - For FTDI CP210x USB to serial chips (small square form factor) * ``sudo modprobe ftdi_sio`` - For FTDI USB to serial chips with multiple serial ports like the FTDI4232H which has 4 serial ports. -After calling these 'modprobe' commands, the result can be verified using ``lsmod`` and rechecking ``dmesg`` to see which ``/dev/ttyUSBxx`` ports were assigned. +After calling these 'modprobe' commands, the result can be verified using ``lsmod`` and re-checking ``dmesg`` to see which ``/dev/ttyUSBxx`` ports were assigned. The ownerchip and permissions of these ``/dev/ttyUSBxx`` are probably set like this: @@ -455,7 +515,7 @@ Writing documentation Updating, or adding if it does not yet exist, the documentation is a useful activity that should be part of changing or adding to the ESPEasy code. Some of the optional VSCode extensions are specifically aimed at that task. -The documentation is created in the reStructuredText format, using mostly a ``.rst`` extension, and can be built locally by installing the sphinx tool. This can be installed manually by opening a Terminal window in VSCode (an already open Terminal can also be used) and issuing these commands: +The documentation is created in the reStructuredText format, using mostly a ``.rst`` extension, and can be built locally by installing the sphinx tool. This can be installed manually by opening a PlatformIO Terminal window in VSCode (an already open PIO Terminal can also be used, when using WSL2 a PlatformIO Terminal is *required* to execute in the correct Python Virtual Environment (venv)) and issuing these commands: .. code-block:: diff --git a/docs/source/Plugin/MCP23017_rev_d.repl b/docs/source/Plugin/MCP23017_rev_d.repl new file mode 100644 index 0000000000..c52fb782d2 --- /dev/null +++ b/docs/source/Plugin/MCP23017_rev_d.repl @@ -0,0 +1,7 @@ +.. note:: Due to technical reasons, the **MCP23017 rev. D** chip no longer has (official) Input capability on the ``GPA7`` and ``GPB7`` pins! + +Following `this news article `_, the MCP23017 I2C chip, since **revision D** released around 2022, might possibly no longer accept signals reliably for Input on the ``GPA7`` and ``GPB7`` pins. Other sources (links no longer available) suggest these pins have had issues taking input signals since at least 2014, so your milage may vary! (Output is still working as usual on these pins.) + +This may have impact on the use of this board/chip with this plugin when using a MCP23017 rev. D. + +Possible alternatives are using an older revision of this chip, or switching to a different chip, like PCF8574 (8 I/O pins), PCF8575 (16 I/O pins, external pull-up), 74HC165 (Input only), 74HC595 (Output only). diff --git a/docs/source/Plugin/P009.rst b/docs/source/Plugin/P009.rst index 16387dea3d..cba06c135e 100644 --- a/docs/source/Plugin/P009.rst +++ b/docs/source/Plugin/P009.rst @@ -37,6 +37,8 @@ Supported hardware The chip can be used on specifically designed hardware, or a generic module can be used. These are available from several sources. +.. include:: MCP23017_rev_d.repl + |P009_usedby| Configuration diff --git a/docs/source/Plugin/P020.rst b/docs/source/Plugin/P020.rst index 0373e404db..65f75a347a 100644 --- a/docs/source/Plugin/P020.rst +++ b/docs/source/Plugin/P020.rst @@ -81,7 +81,7 @@ When selecting the **Event processing** options *Generic* or *RFLink*, after sub * *(Unchecked)* -> ``Serial`` * *HW Serial0* -> ``serial0`` -* *HW Serial0 swap* -> ``serial0`` +* *HW Serial0 swap* -> ``serial0swap`` * *HW Serial1* -> ``serial1`` * *HW Serial2* -> ``serial2`` * *SW Serial* -> ``serialsw`` diff --git a/docs/source/Plugin/P021.rst b/docs/source/Plugin/P021.rst index d89adb11ef..d0ae31017a 100644 --- a/docs/source/Plugin/P021.rst +++ b/docs/source/Plugin/P021.rst @@ -33,11 +33,85 @@ It is always helpful to have some sort of local level control. This is something The ESP module can be used as a level controlling device, think of a simple temperature control unit. Use a DS18B20, BME280 or similar temperature sensor and a mechanical or solid state relay to control a heater. Connect this relay to a GPIO pin. +The control algorithm can be a simple value to setpoint comparator with hysteresis to prevent the relay switching too often in a short period. +Pumps like used for floor heating have some additional requirements like running once in a while and keeping the pump running for a minimum time. +The plugin provides a simple "Classic" mode of operation which can be extended with additional features. + +Note: Due to size limitations some builds contain limited functionality. State control extension and remote control will not be available on these standard builds for ESPeasy. You can always create a custom build with full functionality. + +Basic control algorithm +^^^^^^^^^^^^^^^^^^^^^^^ + +The output of another plugin is used as measurement input. This input is compared with a given Setpoint. If the Input is above the Setpoint the Output (heater/pump) should be switched on (becomes active); +If it is below the setpoint the Output should be switched off (becomes inactive). +If the Input is close to the Setpoint the controller might switch very rapidly between on and off (flip-flopping). This may destroy the relay or pump. A margin between switch on and switch off level is used to prevent this flip-flopping. +When the Input value stays between these two levels the output will not be changed. This margin is called Hysteresis. +The Hysteresis can be symetrical around the Setpoint: Switching on above (Setpoint + 0.5*Hysteresis) and switching off below (Setpoint - 0.5*Hystersis). +With an asymetrical Hysteresis the output is switched on above the Setpoint and switched of below (Setpoint - Hysteresis). + +In case of symetrical hysteresis there is an exception in hysteresis handling: If the Hysteresis is set to 0, the output state will become active if the measured value goes *below* Setpoint, and the output state will become inactive if the measured value reaches ``Setpoint + 1.0``. +It is strongly advised to use a proper non-zero Hysteresis tuned to the behavior of the control process and not to rely on this exception. + +To facilitate various applications the direction of the input comparator can be inverted. +Combining symetrical hystersis and invert output this results in the following overview: + +.. image:: P021_control.png + :alt: Control algorithm overview + +State control extension +^^^^^^^^^^^^^^^^^^^^^^^ + +To provide additional control features the controller can be in one of several States. Based upon the input value and some timers the controller can change the State. The output of the controller directly depends on the State. +The following states exist: + +* **Idle** : The Output is swiched to inactive (off). There is no reason to switch it active (on). +* **Active** : The basic comparator algorithm decides the Output must be switched to active. There is a demand based upon the measured Input value. +* **Extend** : The Output was switched on for a too short period. It will be kept running for a minimum time even while the comparator algorithm has no demand. +* **Force** : The output is forced on for a minimum amount of time to keep the system in condition. The State will be set to Forced when the Output is inactive for a too long time. + +Extension of the period the Output is kept active depends on the use case. Extension from the moment of activating the Output is used to prevent a heater or pump is running too short cycles. +Extension when the demand drops (input below setpoint) is used optimize the control process. For example a heating pump is kept running for some time to spread the remaining heat. + +Remote control +^^^^^^^^^^^^^^ + +It may be useful to manipulate the local controller from a Home Automation controller. The plugin accepts commands to change the following settings: + +* **Setpoint** : This command changes the actual Setpoint for the local control algorithm. +* **Hysteresis** : This command changes the actual Hysteresis for the local control algorithm. +* **Remote** : This command can override the basic control algorithm. It can be used to force the Output to on. Usecase is a floor heating pump that should be switched on as soon as the central heating system is swiched on. + +Operation modes +^^^^^^^^^^^^^^^ + +The controller can be set to one of the following operation modes: + +* **CLASSIC** : Basic control algorithm without state control extension. This mode is backwards compatible with earlier versions of this plugin. +* **OFF** : The output is always switched off. +* **STANDBY** : The output is off with the maintenance check active. The output is switched on after maximum idle time. +* **ON** : The output is always switched on. +* **LOCAL** : Control algorithm with state control extension. Only local control input is used. +* **REMOTE** : Control algorithm with state control extension. Both local control and remote command input is used. + +Backwards compatibility +^^^^^^^^^^^^^^^^^^^^^^^ + +This plugin is extended with new state control features. New settings are added such that existing users should not need to modify their settings when upgrading to a newer ESPeasy version. +As a result some of the added settings may seem a bit strange as they must default to the original behavior. +To achieve this behavior CLASSIC control mode with symetrical Hysteresis is selected as default. + Configuration ------------- -.. image:: P021_DeviceConfiguration.png - :alt: Device Configuration +Configuration settings in classic mode: + +.. image:: P021_DeviceConfiguration1.png + :alt: Device Configuration classic settings + +In extended mode additional settings are available: + +.. image:: P021_DeviceConfiguration2.png + :alt: Device Configuration extended settings * **Name** A unique name should be entered here. @@ -46,23 +120,45 @@ Configuration Sensor ^^^^^^ -* **GPIO -> Level low** Select a GPIO pin that will be updated when the Level state changes. The state is applied directly on the GPIO pin, so only On (1) and Off (0) will be set. - -* **Check Task** Select the Task that should be monitored. Initially the first Task will be selected. Only configured tasks can be selected. +* **GPIO -> Output** Select a GPIO pin that will be updated when the Output state changes. The state is applied directly on the GPIO pin, so only On (1) and Off (0) will be set. -* **Check Value** After selecting the task, the value that should be monitored can be selected. Initially, the first value of the task is selected. +* **Input Task** Select the Task that should be monitored. Initially the first Task will be selected. Only configured tasks can be selected. -* **Set Level** The value that is to be maintained. Decimals can be used in this value. +* **Input Value** After selecting the task, the value that should be monitored can be selected. Initially, the first value of the task is selected. -* **Hysteresis** To avoid 'flip-flopping' of the output, some hysteresis should be applied to the **Set Value**. The value entered here will be applied 'around' that set value, so half of the hysteresis below Set Value will turn on (1) the output state, and half of the hysteresis above the set value will turn off (0) the output state. +* **Setpoint** The value that is to be maintained. Decimals can be used in this value. -There is 1 exception to the **Hysteresis**: If the Hysteresis is set to 0, the output state will turn on (1) if the measured value goes *below* Set Value, and the output state will turn off (0) if the measured value reaches ``Set Value + 1.0``. +* **Hysteresis** To avoid 'flip-flopping' of the output, some hysteresis should be applied to the **Setpoint**. The value entered here will be applied as described above in Basic control algorithm. -* **Invert Output**: When checked, the output state will be 0 instead of 1 when the level is activated. +* **Invert Output** When checked, the output state will be 0 instead of 1 when the level is activated. * **Save 'Set Level' after change via config command** Via the config command, the **Set Level** value can be changed. To avoid wearing out the flash memory of the device by too often saving these settings, the default is now off, for existing tasks (after upgrade of ESPEasy), the old behavior of saving after each change is still active. The user should decide if saving the setting is actually required, or if that can be attained by carefully planning a save command or via a manual save. -* **Auto-save interval**: Here a time in minutes can be set after which any changed 'Set Level' via the ``config,task,,SetLevel,`` command will be saved. This *requires* that the above setting **Save 'Set Level' after change via config command** is **disabled**! When used, a setting of ca. 30 minutes, or even longer when the Set Level is changed often, seems apropriate, unless the unit often reboots, but then that cause should be investigated and solved. The timer, when activated, should survive a warm reboot. +* **Auto-save interval** Here a time in minutes can be set after which any changed 'Set Level' via the ``config,task,,SetLevel,`` command will be saved. This *requires* that the above setting **Save 'Set Level' after change via config command** is **disabled**! When used, a setting of ca. 30 minutes, or even longer when the Set Level is changed often, seems apropriate, unless the unit often reboots, but then that cause should be investigated and solved. The timer, when activated, should survive a warm reboot. + +* **Extended functionality**:sup:`1)` Enable new functionality. Changing this will reload the form showing/hiding the new options below. + +* **Long time span**:sup:`1)` Timer values are per default entered in [seconds], enabling this option timing settings are tuned to long intervals using [hours] or [seconds]. Changing this will reload the form showing rescaled values and new units. + +* **Control mode**:sup:`1)` Selection of the Control mode, see Operation mode above. + +* **Minimum running time**:sup:`1)` Once switched on the Output shall be active for at least this time. See State control extension. Time is either in [seconds] or in [minutes]. + +* **Maximum idle time**:sup:`1)` Output will be forced to active if it has been idle for this time. See State control extension. Time is either in [seconds] or in [hours]. + +* **Forced circulation time**:sup:`1)` Output will be active for this duration once it is forced active. See State control extension. Time is either in [seconds] or in [minutes]. + +* **Symetrical hysteress**:sup:`1)` If checked the Hysteresis is symerical around the Setpoint. Otherwise it is asymertical. See basic control algorithm. + +* **Extend at end**:sup:`1)` If checked the extension period is started after demand dropt, otherwise the extension period timing is started when the Output is switched to active. + +* **Invert Input**:sup:`1)` If checked the input compare direction is inverted. See basic control algorithm above. + +* **Slow evaluation**:sup:`1)` By default the control algorithm is evaluated 10 times per second. Many applications don't need this speed. Checking this setting evaluates the control algorithm once per second to reduce the CPU load. + +* **State as output value**:sup:`1)` This adds the calculated state as a second value. This can be used in rules to show what the controller is doing. + +:sup:`1)` Configuration may not be available due to build size limitations. Data Acquisition ^^^^^^^^^^^^^^^^ @@ -72,7 +168,8 @@ This group of settings, **Single event with all values** and **Send to Controlle Values ^^^^^^ -The output state value is available in ``Output``. No other options are available for Values. +The output value is available in ``Output``. +In case **State as output value** is checked also the internal state is available in ``State``. Commands available @@ -83,7 +180,72 @@ Commands available Events ~~~~~~ -When the ``Output`` state changes, an event is generated, with the new state as the payload, so this change can also be handled using Rules. +When the ``State`` value changes, an event with the new output and state as the payload is generated. +So this change can also be handled using Rules. + + +example +------- + +I am using this plugin to control a water circulation pump for my floor heating at house. The house is heated by a central heating system (boiler and heatpump combination). +The circulation pump consumes quite some electricity, so I only want to switch it on only when needed. The control box contains an ESP32 with 3 temperature sensors to monitor: + +* Water temperature from the heater + +* Water temperature floor inlet + +* Water termperature floor outlet + +It has one output to control the pump. + +Control input is the water temperature from the central heating. If the temparture rises above the **Setpoint** (heating switched on by the thermostat in the room) the pump is switched on. +When the temperature drops below the **Setpoint** minus **Hysteresis** it can be switched off. +However, it shall run for some extension time to assure the remaining heat in the water is spread well over the floor. It also prevents switching the pump too often which might damage it. +These pumps don't like it when idling for half a year. Therefore the pump is switched on for 5 minutes in case is has not been running for a day. +With the introduction of the heat pump the water temperature stays relatively low (40 degrees) and the pump might be switched on very late. Therefore the home automation system sends a "remote on" when the heat pump is running. +Note that setting the setpoint very low will result in switching on the pump in summer due to high environmental temperatures. I have a small margin here or have to switch the **Control mode** to STANDBY in summer. + +The control box has a 3 color LED to signal the state. I use a rule to use the state value to enable one of the LED outputs: + +* IDLE : green LED + +* HEATING : red LED + +* EXTEND, FORCE : blue LED + +My settings: + +* **Setpoint** 25 + +* **Hysteresis** 4 + +* **Invert Output** false + +* **Save 'Set Level' after change via config command** false. + +* **Auto-save interval** 0 + +* **Extended functionality** YES + +* **Long time span** YES + +* **Control mode** Remote + +* **Minimum running time** 30 min + +* **Maximum idle time** 24 hour + +* **Forced circulation time** 5 min + +* **Symetrical hysteress** false + +* **Extend at end** true + +* **Invert Input** false + +* **Slow evaluation** true + +* **State as output value** true Change log ---------- @@ -91,6 +253,9 @@ Change log .. versionchanged:: 2.0 ... + |added| + 2024-07-11: overhaul, added state control extensions. + |added| 2023-10-28: Set Hysteresis via ``config`` command and get via ``[#GetHysteresis]`` variable. diff --git a/docs/source/Plugin/P021_DeviceConfiguration1.png b/docs/source/Plugin/P021_DeviceConfiguration1.png new file mode 100644 index 0000000000..43b3e15658 Binary files /dev/null and b/docs/source/Plugin/P021_DeviceConfiguration1.png differ diff --git a/docs/source/Plugin/P021_DeviceConfiguration2.png b/docs/source/Plugin/P021_DeviceConfiguration2.png new file mode 100644 index 0000000000..5ace159c52 Binary files /dev/null and b/docs/source/Plugin/P021_DeviceConfiguration2.png differ diff --git a/docs/source/Plugin/P021_commands.repl b/docs/source/Plugin/P021_commands.repl index 40f9f74a58..df1114d62c 100644 --- a/docs/source/Plugin/P021_commands.repl +++ b/docs/source/Plugin/P021_commands.repl @@ -23,6 +23,22 @@ Using this command, either from rules, via http or mqtt, the **Hysteresis** of the plugin can be changed. If the new value differs from the currently set hysteresis, the settings are saved. " " + ``config,task,,Remote,`` + + Value: {A valid numeric (bool) value } + + "," + Using this command, either from rules, via http or mqtt, the remote control state of the plugin can be changed. When result is true and control mode is remote the Output will be set to active. When result is false local control algorithm is used. This value is never saved. + " + " + ``levelcontrol,Remote,[0|1]`` + + Value: {**0** or **1** } + + "," + Using this command, either from rules, via http or mqtt, the remote control state of the plugin can be changed. If the value is **1** and control mode is remote the Output will be set to active. If the value is **0** local control algorithm is used. This value is never saved. + " + " ``[#GetLevel]`` "," Not a real command, but this plugin supports the ``GetLevel`` Config function, to retrieve the **Set Value** from the settings, by using the pseudo value ``GetLevel``. diff --git a/docs/source/Plugin/P021_control.png b/docs/source/Plugin/P021_control.png new file mode 100644 index 0000000000..800432f1c8 Binary files /dev/null and b/docs/source/Plugin/P021_control.png differ diff --git a/docs/source/Plugin/P022_commands.repl b/docs/source/Plugin/P022_commands.repl index 78d1a64edb..ebdf27d45e 100644 --- a/docs/source/Plugin/P022_commands.repl +++ b/docs/source/Plugin/P022_commands.repl @@ -7,7 +7,7 @@ ``[].pwm,,[,]`` - pcagpio: 0 ... 255 + pcagpio: 0 ... 15 value: 0 ... 4096 @@ -25,7 +25,7 @@ " ``[].gpio,,`` - pcagpio: 0 ... 255/all + pcagpio: 0 ... 15/all value: 0/1 "," @@ -36,7 +36,7 @@ " ``[].pulse,,,[,|auto]`` - pcagpio: 0 ... 255 + pcagpio: 0 ... 15 value: 0/1 diff --git a/docs/source/Plugin/P045.rst b/docs/source/Plugin/P045.rst index 716a296bd1..b2527838f6 100644 --- a/docs/source/Plugin/P045.rst +++ b/docs/source/Plugin/P045.rst @@ -33,9 +33,9 @@ Configuration .. image:: P045_DeviceConfiguration.png -**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. I2C Options ^^^^^^^^^^^^ @@ -47,7 +47,7 @@ The available settings here depend on the build used. At least the **Force Slow Device Settings ^^^^^^^^^^^^^^^^ -* **Function** Select the function this task should perform. +* **Function**: Select the function this task should perform. Available options: @@ -61,11 +61,11 @@ When selecting the **Movement detection** function, additional configuration is The Detection threshold can be configured per X, Y and Z axis (range 0..65535) and will be triggered when it exceeds the set threshold, where the axis is ignored if the threshold is set to 0. An actual threshold can be determined by selecting one of the Acceleration X/Y/Z functions, and making note of the value measured while an expected movement is applied to the sensor. -* **Detection on all 3 axes** When this option is enabled, all 3 axes need to exceed the configured threshold for the counter to be increased. When disabled, only one of the axis need to exceed the threshold to cause an increment. +* **Detection on all 3 axes**: When this option is enabled, all 3 axes need to exceed the configured threshold for the counter to be increased. When disabled, only one of the axis need to exceed the threshold to cause an increment. -* **Min. detection count** The minimum count of movements during the **Detection window** before the count is reset. +* **Min. detection count**: The minimum count of movements during the **Detection window** before the count is reset. -* **Detection window** The number of interval passes before the counter is actually increased. +* **Detection window**: The number of interval passes before the counter is actually increased. Every 30 seconds a counter for the detection window is increased plus all axis are checked and if they *all* (or any when **Detection on all 3 axes** is unchecked) that are enabled exceeded the threshold values, a counter is increased. @@ -73,18 +73,31 @@ Each period, defined by the **Detection window**, the counter is checked against If in the next window the **Min. detection count** value is not met, movement has stopped. The **Detection window** cannot be smaller than the **Min. detection count**. +Other measurements +~~~~~~~~~~~~~~~~~~ + +When **Function** is set to one of the measurement options, **Range acceleration**, **Acceleration** or **G-force**, the settings related to Movement detection will be hidden: + +.. image:: P045_All3ValuesCheckbox.png + +* **Provide all 3 values (X/Y/X)**: When unchecked (default), the selected raw X/Y/Z value will be available as the single value in the **Values** section, below. When *checked*, all 3 X, Y and Z values for the selected function will be available in the **Values** section, always in ``X``, ``Y``, ``Z`` order. Most usable would be to name them accordingly. + +.. image:: P045_All3Values.png + Data Acquisition ^^^^^^^^^^^^^^^^ -The Single event with all values, Send to Controller and Interval settings are standard available configuration items. Send to Controller is only shown when one or more Controllers are configured. +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 minimum value allowed is 1 sec. +**Interval**: By default, Interval will be set to 60 sec. The minimum value allowed is 1 sec. Values ^^^^^^ The measured value or the counter are available here, by default no name is given for the value, as this is usually chosen based on the function. No formula or decimals are available. +In selected builds, per Value a **Stats** and **Hide** checkbox and an **Axis** selection combobox are available, that when Statis is checked, gathers the data and presents recent data, based on the **Interval**, in a graph, as described here: :ref:`Task Value Statistics: ` + Change log ---------- @@ -92,6 +105,9 @@ Change log .. versionchanged:: 2.0 ... + |added| + 2024-11-03 Checkbox for selecting all 3 X/Y/Z values for a measurement. + |added| 2022-05-05 Checkbox for selecting ALL or ANY axis movement detection. diff --git a/docs/source/Plugin/P045_All3Values.png b/docs/source/Plugin/P045_All3Values.png new file mode 100644 index 0000000000..1145060749 Binary files /dev/null and b/docs/source/Plugin/P045_All3Values.png differ diff --git a/docs/source/Plugin/P045_All3ValuesCheckbox.png b/docs/source/Plugin/P045_All3ValuesCheckbox.png new file mode 100644 index 0000000000..d46252ab03 Binary files /dev/null and b/docs/source/Plugin/P045_All3ValuesCheckbox.png differ diff --git a/docs/source/Plugin/P045_DeviceConfiguration.png b/docs/source/Plugin/P045_DeviceConfiguration.png index 3a2b44d7ef..19bbc27a8d 100644 Binary files a/docs/source/Plugin/P045_DeviceConfiguration.png and b/docs/source/Plugin/P045_DeviceConfiguration.png differ diff --git a/docs/source/Plugin/P053.rst b/docs/source/Plugin/P053.rst index 15982414c2..94fbe6c5b8 100644 --- a/docs/source/Plugin/P053.rst +++ b/docs/source/Plugin/P053.rst @@ -23,145 +23,7 @@ Maintainer: |P053_maintainer| Used libraries: |P053_usedlibraries| -Introduction ------------- - -The Plantower PMSx003 modules are laser based particle sensors. - -Particles are measured by blowing air through the enclosure with a laser inside. By measuring diffusion of the laser beam, the amount of particles is counted. - -Measurement information is transmitted over a serial interface. - -In opposition to the GP2Y10 this sensors have an own microprocessor that does reading and differing into the PM1.0, PM2.5 and PM10 sizes. The values can be read directly from the serial interface. - -Units of Measure ----------------- - -Dust Particles -^^^^^^^^^^^^^^ - -All supported Plantower PMSx003 modules can measure the concentration of dust particles, binned per size of the particle. - -The measured values are either in counts per 0.1 liter, or in µg/m3. - -To indicate the kind of particles that can be measured by the Plantower sensors: - -.. image:: P053_Particulates_chart.png - -`Image source `_ - - -The counts per 0.1 liter can be specified in a larger number of bins. -However, the Plantower particle sensors appear to be estimating particles larger than roughly 2.5 - 3 micron. -The bins ranging from 0.3 ... 2.5 micron are actually being measured, but the larger ones are estimates. -This has as side effect that it may not show anything if there are no particles smaller than roughly 3 micron. - -Conversion count/100ml to mg/m3 -""""""""""""""""""""""""""""""" - -Conversion between counts per volume into weight per volume (e.g. mg/m3) is a bit more complicated than using a single multiplier factor. -As can be seen in the particle size chart above, the average molecular weight of particles will be different per bin and also there is no such thing as an universal mixture ratio of particles all over the world. - -There seem to be standardized conversion factors for: - -* PM10 consists of coarse particles that have diameters that are less than or equal to 10 micrometres -* PM2.5 consists of fine particles with diameters less than or equal to 2.5 micrometres -* PM1 (particles <= 1 micron) - -However, a simple conversion rate is hard to find even though it seems to be standardized. -What makes it even harder to perform such a conversion from counts per volume to weight per volume is the fact that the Plantower sensors count particles of a specific size and above. - -For example: - -* PM2.5 is about particles **less than or equal** to 2.5 micrometres -* cnt2.5/100ml indicates the number of particles with diameter **beyond** 2.5 micrometres in 0.1 L of air. (datasheet Plantower PMS5003) - -.. note:: ``PMxx`` values relate to particles **less than or equal** to said size, while count/100ml relates to particles of **at least** said size. - Except when "Split count bins" is checked, then the "count/0.1L" values represent only a single bin. - - -Effects of Humidity -""""""""""""""""""" - -There are some reports suggesting that some particles may stick together causing a shift in the bins. -For example, if one would draw a histogram of the counted particles per bin, the chart would appear to be shifted a bit to the more larger particles. - -.. image:: P053_effect_humidity_measurement.png - -`Image source `_ - -The apparent size shift vs. humidity is only for soluble particles. -Water won't adhere to insoluble particles, so high humidity won't affect particle counts of soot, ash, or most dusts, but it will have an effect with salts (like sea salt spray) or organic compounds. - -In some setups this may also make the counted values appear lower, since the sensor can only estimate the particles larger than 3 micron if there are also smaller particles detected. -When the smaller particles all stick together thus no small particles will be observed by the sensor, the reading may be (much) lower than it actually should be. -Try to have the sensor running in environments with relatively low humidity (less than 80%). - -A very good video describing hazards of dust particles: `Sabine Hossenfelder - How bad is Diesel? `_ - -Air Quality Index -""""""""""""""""" - -There is a lot of information to be found online about the effects and health issues of exposure to dust particles. -For example the UK guidelines of average daily exposure on Wikipedia: - -.. image:: P053_AirQualityIndex_Wikipedia.png - -Source: `Wikipedia - Air Quality Index `_ - -Such an Air Quality Index can then be used to indicate the maximum exposure (in days per year) which can be considered safe. - -A website to check your local air quality: `IQAir ` - -Temperature/Humidity -^^^^^^^^^^^^^^^^^^^^ - -Plantower sensors with ``T`` or ``ST`` in their model name, can also measure temperature and humidity. - -It is likely that the modules capable of measuring humidity can also compensate for this humidity when calculating the concentration in µg/m3. -However, so far it is unclear whether these sensors actually do compensate for this as humidity might cause the smaller particles to stick together. -But this depends on the type of particles as not all may adhere to water, which makes it almost impossible to have a simple universal compensation factor for humidity. - -It is up to the user to interpret (and correct) the data, as the user may have more information on the composition of the measured air. - - -Formaldehyde -^^^^^^^^^^^^ - -Plantower sensors with ``S`` or ``ST`` in their model name, can also measure Formaldehyde. - -When comparing concentration levels, one may encounter concentrations in ppm or µg/m3. - -To compare these, use as conversion factor: 1 ppm = 1.25 mg/m3 (1 atm pressure, 20 degree C) - -The Plantower sensors report the concentration in mg/m3. - - -The information below on Formaldehyde is an excerpt of the online found documents, written by `WHO Regional Office for Europe, Copenhagen, Denmark, 2001 `_ - -Formaldehyde is the most common aldehyde in the environment. The natural background concentration is < 1 µg/m3 with a mean of about 0.5 µg/m3. - -In urban environments, outdoor air concentrations are more variable and depend on local conditions; -annual averages are usually between 1 and 20 µg/m3. - -Short-term peaks, e.g. in heavy traffic or during severe inversions, can range up to 100 µg/m3. (0.1 mg/m3) -The levels of formaldehyde in indoor air are often higher than those in outdoor air. -Major sources of formaldehyde in some dwellings are off-gassing of urea–formaldehyde foam insulation, particle board and formaldehyde-based resins. -In the early 1980s, mean levels of 490 µg/m3 were measured in mobile homes, with individual measurements as high as several mg/m3 in new mobile homes. -Now formaldehyde levels in mobile homes are typically around 100 µg/m3 or less. -Mean levels in conventional homes with no urea–formaldehyde foam insulation range from 25 to 60 µg/m3 - - -Exposure Guidelines -""""""""""""""""""" - -Formaldehyde has been shown to be toxic in higher concentrations. -Concentration was more important than dose (concentration × length of exposure) in determining the cytotoxic effects of formaldehyde. - -* A short-term (30-minute) guideline of 0.1 mg/m3 is recommended as preventing sensory irritation in the general population. -* A long-term exposure guideline of 0.21 mg/m3 for the protection of health for long-term effects, including cancer. - -Source: `WHO Guidelines for Indoor Air Quality: Selected Pollutants `_ +.. include:: P053_P175_common.repl Supported hardware ------------------ diff --git a/docs/source/Plugin/P053_EventOptions.png b/docs/source/Plugin/P053_EventOptions.png index 951e32b506..259983e53f 100644 Binary files a/docs/source/Plugin/P053_EventOptions.png and b/docs/source/Plugin/P053_EventOptions.png differ diff --git a/docs/source/Plugin/P053_OutputValuesOptions.png b/docs/source/Plugin/P053_OutputValuesOptions.png index db3b1d4269..860232b65a 100644 Binary files a/docs/source/Plugin/P053_OutputValuesOptions.png and b/docs/source/Plugin/P053_OutputValuesOptions.png differ diff --git a/docs/source/Plugin/P053_P175_common.repl b/docs/source/Plugin/P053_P175_common.repl new file mode 100644 index 0000000000..0760e789a3 --- /dev/null +++ b/docs/source/Plugin/P053_P175_common.repl @@ -0,0 +1,139 @@ +Introduction +------------ + +The Plantower PMSx003 modules are laser based particle sensors. + +Particles are measured by blowing air through the enclosure with a laser inside. By measuring diffusion of the laser beam, the amount of particles is counted. + +Measurement information is transmitted over a serial interface. + +In opposition to the GP2Y10 this sensors have an own microprocessor that does reading and differing into the PM1.0, PM2.5 and PM10 sizes. The values can be read directly from the serial interface. + +Units of Measure +---------------- + +Dust Particles +^^^^^^^^^^^^^^ + +All supported Plantower PMSx003 modules can measure the concentration of dust particles, binned per size of the particle. + +The measured values are either in counts per 0.1 liter, or in µg/m3. + +To indicate the kind of particles that can be measured by the Plantower sensors: + +.. image:: P053_Particulates_chart.png + +`Image source `_ + + +The counts per 0.1 liter can be specified in a larger number of bins. +However, the Plantower particle sensors appear to be estimating particles larger than roughly 2.5 - 3 micron. +The bins ranging from 0.3 ... 2.5 micron are actually being measured, but the larger ones are estimates. +This has as side effect that it may not show anything if there are no particles smaller than roughly 3 micron. + +Conversion count/100ml to mg/m3 +""""""""""""""""""""""""""""""" + +Conversion between counts per volume into weight per volume (e.g. mg/m3) is a bit more complicated than using a single multiplier factor. +As can be seen in the particle size chart above, the average molecular weight of particles will be different per bin and also there is no such thing as an universal mixture ratio of particles all over the world. + +There seem to be standardized conversion factors for: + +* PM10 consists of coarse particles that have diameters that are less than or equal to 10 micrometres +* PM2.5 consists of fine particles with diameters less than or equal to 2.5 micrometres +* PM1 (particles <= 1 micron) + +However, a simple conversion rate is hard to find even though it seems to be standardized. +What makes it even harder to perform such a conversion from counts per volume to weight per volume is the fact that the Plantower sensors count particles of a specific size and above. + +For example: + +* PM2.5 is about particles **less than or equal** to 2.5 micrometres +* cnt2.5/100ml indicates the number of particles with diameter **beyond** 2.5 micrometres in 0.1 L of air. (datasheet Plantower PMS5003) + +.. note:: ``PMxx`` values relate to particles **less than or equal** to said size, while count/100ml relates to particles of **at least** said size. + Except when "Split count bins" is checked, then the "count/0.1L" values represent only a single bin. + + +Effects of Humidity +""""""""""""""""""" + +There are some reports suggesting that some particles may stick together causing a shift in the bins. +For example, if one would draw a histogram of the counted particles per bin, the chart would appear to be shifted a bit to the more larger particles. + +.. image:: P053_effect_humidity_measurement.png + +`Image source `_ + +The apparent size shift vs. humidity is only for soluble particles. +Water won't adhere to insoluble particles, so high humidity won't affect particle counts of soot, ash, or most dusts, but it will have an effect with salts (like sea salt spray) or organic compounds. + +In some setups this may also make the counted values appear lower, since the sensor can only estimate the particles larger than 3 micron if there are also smaller particles detected. +When the smaller particles all stick together thus no small particles will be observed by the sensor, the reading may be (much) lower than it actually should be. +Try to have the sensor running in environments with relatively low humidity (less than 80%). + +A very good video describing hazards of dust particles: `Sabine Hossenfelder - How bad is Diesel? `_ + +Air Quality Index +""""""""""""""""" + +There is a lot of information to be found online about the effects and health issues of exposure to dust particles. +For example the UK guidelines of average daily exposure on Wikipedia: + +.. image:: P053_AirQualityIndex_Wikipedia.png + +Source: `Wikipedia - Air Quality Index `_ + +Such an Air Quality Index can then be used to indicate the maximum exposure (in days per year) which can be considered safe. + +A website to check your local air quality: `IQAir ` + +Temperature/Humidity +^^^^^^^^^^^^^^^^^^^^ + +Plantower sensors with ``T`` or ``ST`` in their model name, can also measure temperature and humidity. + +It is likely that the modules capable of measuring humidity can also compensate for this humidity when calculating the concentration in µg/m3. +However, so far it is unclear whether these sensors actually do compensate for this as humidity might cause the smaller particles to stick together. +But this depends on the type of particles as not all may adhere to water, which makes it almost impossible to have a simple universal compensation factor for humidity. + +It is up to the user to interpret (and correct) the data, as the user may have more information on the composition of the measured air. + + +Formaldehyde +^^^^^^^^^^^^ + +Plantower sensors with ``S`` or ``ST`` in their model name, can also measure Formaldehyde. + +When comparing concentration levels, one may encounter concentrations in ppm or µg/m3. + +To compare these, use as conversion factor: 1 ppm = 1.25 mg/m3 (1 atm pressure, 20 degree C) + +The Plantower sensors report the concentration in mg/m3. + + +The information below on Formaldehyde is an excerpt of the online found documents, written by `WHO Regional Office for Europe, Copenhagen, Denmark, 2001 `_ + +Formaldehyde is the most common aldehyde in the environment. The natural background concentration is < 1 µg/m3 with a mean of about 0.5 µg/m3. + +In urban environments, outdoor air concentrations are more variable and depend on local conditions; +annual averages are usually between 1 and 20 µg/m3. + +Short-term peaks, e.g. in heavy traffic or during severe inversions, can range up to 100 µg/m3. (0.1 mg/m3) +The levels of formaldehyde in indoor air are often higher than those in outdoor air. +Major sources of formaldehyde in some dwellings are off-gassing of urea–formaldehyde foam insulation, particle board and formaldehyde-based resins. +In the early 1980s, mean levels of 490 µg/m3 were measured in mobile homes, with individual measurements as high as several mg/m3 in new mobile homes. +Now formaldehyde levels in mobile homes are typically around 100 µg/m3 or less. +Mean levels in conventional homes with no urea–formaldehyde foam insulation range from 25 to 60 µg/m3 + + +Exposure Guidelines +""""""""""""""""""" + +Formaldehyde has been shown to be toxic in higher concentrations. +Concentration was more important than dose (concentration × length of exposure) in determining the cytotoxic effects of formaldehyde. + +* A short-term (30-minute) guideline of 0.1 mg/m3 is recommended as preventing sensory irritation in the general population. +* A long-term exposure guideline of 0.21 mg/m3 for the protection of health for long-term effects, including cancer. + +Source: `WHO Guidelines for Indoor Air Quality: Selected Pollutants `_ diff --git a/docs/source/Plugin/P054.rst b/docs/source/Plugin/P054.rst index ad5de6617e..e1cf1f9061 100644 --- a/docs/source/Plugin/P054.rst +++ b/docs/source/Plugin/P054.rst @@ -1,4 +1,4 @@ -.. include:: ../Plugin/_plugin_substitutions_p05x.repl +.. include:: ../Plugin/_plugin_substitutions_p05x.repl .. _P054_page: |P054_typename| @@ -21,15 +21,59 @@ Maintainer: |P054_maintainer| Used libraries: |P054_usedlibraries| -Supported hardware ------------------- - |P054_usedby| -.. Commands available -.. ^^^^^^^^^^^^^^^^^^ +Description +----------- + +For controlling DMX512 equipment, this plugin can be used for sending commands to a DMX bus. As an ESP only has a 5V compatible serial interface, usually a RS485 or DMX converter is needed to connect to the DMX bus. + +This plugin can only send out commands to the DMX bus, no receiving or recording features are available. + +Configuration +------------- + +.. image:: P054_DeviceConfiguration.png + +* **Name** In the Name field a unique name should be entered. + +* **Enabled** When unchecked the plugin is not enabled. + +Actuator +^^^^^^^^ + +See: :ref:`SerialHelper_page` + +.. warning:: The selected serial port **must** use on-ESP GPIO pins, as the DMX protocol has some specific coding that is not supported by regular serial chips, and is implemented by directly interacting with the ESP TX pin. + +Example selection list (taken from an ESP32-C6 configuration): + +.. image:: P054_SerialPortOptions.png -.. .. include:: P054_commands.repl +* *HW Serial0*: First serial port, usually also in use for the serial log, so should best be avoided. + +* *HW Serial1*: Secondary serial port. Selected as the default, and required to be used on ESP8266. + +* *HW Serial2*: (Not available on an ESP32-C6, but is available on some other ESP32 models) Can be used. + +* *SW Serial*: Can be tried, and used if working as intended, but should better be avoided because of the high serial speed (250000 baud). + +* *USB HWCDC*: Can not be used. + +* *USB CDC*: Can not be used. + +* *I2C Serial*: Can not be used. + +Device Settings +^^^^^^^^^^^^^^^ + +* **Channels**: The number of DMX channels to be used. Determines the size of a memory buffer. Keep as small as possible, especially on ESP8266, where available memory can be limited. + + +Commands available +^^^^^^^^^^^^^^^^^^ + +.. include:: P054_commands.repl .. Events .. ~~~~~~ @@ -42,6 +86,8 @@ Change log .. versionchanged:: 2.0 ... + |added| 2024-09-29: Add selection for Serial port and GPIO on ESP32. + |added| Major overhaul for 2.0 release. diff --git a/docs/source/Plugin/P054_DeviceConfiguration.png b/docs/source/Plugin/P054_DeviceConfiguration.png new file mode 100644 index 0000000000..05154a12d5 Binary files /dev/null and b/docs/source/Plugin/P054_DeviceConfiguration.png differ diff --git a/docs/source/Plugin/P054_SerialPortOptions.png b/docs/source/Plugin/P054_SerialPortOptions.png new file mode 100644 index 0000000000..c981b596fd Binary files /dev/null and b/docs/source/Plugin/P054_SerialPortOptions.png differ diff --git a/docs/source/Plugin/P054_commands.repl b/docs/source/Plugin/P054_commands.repl new file mode 100644 index 0000000000..baf5120ba1 --- /dev/null +++ b/docs/source/Plugin/P054_commands.repl @@ -0,0 +1,39 @@ +.. csv-table:: + :header: "Command Syntax", "Extra information" + :widths: 20, 30 + + " + | ``dmx,log`` + "," + | List the current content of the send-buffer to the log. + " + " + | ``dmx,test`` + "," + | Fills the send-buffer with random data and sends that to the connected devices. + " + " + | ``dmx,on`` + "," + | Fills the send-buffer all \'255\' values and sends that to the connected devices to turn everthing on. + " + " + | ``dmx,off`` + "," + | Fills the send-buffer all \'0\' values and sends that to the connected devices to turn everthing off. + " + " + | ``dmx,=[,[,=]]`` + + | ``channel``: Channel number from 1 .. **Channels** set in the configuration. + + | ``value``: Numeric value between 0 and 255 (inclusive) to set for the channel. + "," + | Fills the send-buffer given value(s) for the channel and sends that to the connected devices. + + | If no channel is used with a value, it is set for the next channel. The channel is initially set to 1. + + | Multiple values, optionally with a channel prefixed, can be provided and will be processed until no more data is found. + + | Also, other subcommands (not including ``dmx``) can be used, f.e. setting up some channel data and adding a ``,log`` at the end to list the current buffer content to the log output. + " diff --git a/docs/source/Plugin/P061.rst b/docs/source/Plugin/P061.rst index e3a6a0c7d2..daf2c20366 100644 --- a/docs/source/Plugin/P061.rst +++ b/docs/source/Plugin/P061.rst @@ -91,6 +91,8 @@ Often used matrix keypads, in 16 and 12 key configuration: (Image sourced from Aliexpress) +.. include:: MCP23017_rev_d.repl + Configuration ------------- diff --git a/docs/source/Plugin/P103.rst b/docs/source/Plugin/P103.rst index 4560326cb7..e2c984bca9 100644 --- a/docs/source/Plugin/P103.rst +++ b/docs/source/Plugin/P103.rst @@ -27,13 +27,134 @@ Datasheet: |P103_datasheet| Description ----------- +Several Atlas Scientific EZO sensors are supported by this plugin. Only I2C communication is supported, some sensors use that by default, and most other sensors can be re-configured from RS232 to I2C communication. +Currently there is support for: +* **pH**: Potential of Hydrogen (Acidity) -.. Events -.. ~~~~~~ +* **ORP**: Oxidation Reduction Potential + +* **EC**: Electrical Conductivity + +* **DO**: Dissolved Oxigen + +* **HUM**: Humidity (Can also provide Temperature and Dewpoint measurements) + +Device configuration +-------------------- + +.. image:: P103_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` + +When loading the Device configuration page, the plugin will try to detect the type of sensor connected based on the selected I2C addresses. If no sensor is found, the message in red will be shown. + +If no sensor is connected, the configuration can still be shown by selecting the **Setup without sensor** checkbox, choosing the I2C address for the intended sensor, and submitting the page. + +Device settings +^^^^^^^^^^^^^^^ + +Board +^^^^^ + +This section shows relevant information, obtained from the sensor if actually connected. + +* **Status LED**: The status led on the sensor can be enabled or disabled, using this checkbox. + +For each board there are different device parameters available, but when using the device simulation, no actual device information is available, so no data is shown. + +Board pH +^^^^^^^^ + +.. image:: P103_Device_pH.png + +pH Calibration +^^^^^^^^^^^^^^ + +For the pH sensor, some calibration may be needed. The simulated device doesn't have any calibration data set. + +.. image:: P103_Device_pH_Calibration.png + +For compensation of temperature, either a fixed temperature or a value from a connected temperature sensor can be selected. For this connected temperature sensor, the ``[#]`` notation can be used. This will will be evaluated when the value is needed. + +Board ORP +^^^^^^^^^ + +.. image:: P103_Device_ORP.png + +ORP Calibration +^^^^^^^^^^^^^^^ + +For the ORP sensor, some calibration may be needed. The simulated device doesn't have any calibration data set. + +.. image:: P103_Device_ORP_Calibration.png + +For compensation of temperature, either a fixed temperature or a value from a connected temperature sensor can be selected. For this connected temperature sensor, the ``[#]`` notation can be used. This will will be evaluated when the value is needed. + +Board EC +^^^^^^^^ + +.. image:: P103_Device_EC.png + +EC Calibration +^^^^^^^^^^^^^^ + +For the EC sensor, some calibration may be needed. The simulated device doesn't have any calibration data set. + +.. image:: P103_Device_EC_Calibration.png + +For compensation of temperature, either a fixed temperature or a value from a connected temperature sensor can be selected. For this connected temperature sensor, the ``[#]`` notation can be used. This will will be evaluated when the value is needed. + +Board DO +^^^^^^^^ + +.. image:: P103_Device_DO.png + +DO Calibration +^^^^^^^^^^^^^^ + +For the DO sensor, some calibration may be needed. The simulated device doesn't have any calibration data set. + +.. image:: P103_Device_DO_Calibration.png + +Board HUM +^^^^^^^^^ + +.. image:: P103_Device_HUM.png + +HUM Calibration +^^^^^^^^^^^^^^^ + +For the HUM sensor, no calibration can be adjusted, but options to enable the Temperature and/or Dew-point measurements are available. + +.. image:: P103_Device_HUM_Options.png + +To make the Temperature and Dew-point available for use, extra values are available: + +.. image:: P103_Device_HUM_Values.png + +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. The data will be collected and optionally sent to any configured controllers using this interval. + +Values +^^^^^^ + +For all sensors, the **SensorData** and **Voltage** values are available. For the **HUM** Humidity sensor, also **Temperature** and **Dew-point** values are available, but have to be enabled in options to return a sensible value. + +In selected builds, per Value **Stats** options are available, that when enabled, will gather the measured data and present most recent data in a graph, as described here: :ref:`Task Value Statistics: ` -.. .. include:: P103_events.repl @@ -43,4 +164,6 @@ Change log .. versionchanged:: 2.0 ... + |added| 2023-10-17 Add HUM sensor + |added| 2020-04-25 diff --git a/docs/source/Plugin/P103_DeviceConfiguration.png b/docs/source/Plugin/P103_DeviceConfiguration.png new file mode 100644 index 0000000000..08b3cb3848 Binary files /dev/null and b/docs/source/Plugin/P103_DeviceConfiguration.png differ diff --git a/docs/source/Plugin/P103_Device_DO.png b/docs/source/Plugin/P103_Device_DO.png new file mode 100644 index 0000000000..45ee0f97bf Binary files /dev/null and b/docs/source/Plugin/P103_Device_DO.png differ diff --git a/docs/source/Plugin/P103_Device_DO_Calibration.png b/docs/source/Plugin/P103_Device_DO_Calibration.png new file mode 100644 index 0000000000..aca47b6a7e Binary files /dev/null and b/docs/source/Plugin/P103_Device_DO_Calibration.png differ diff --git a/docs/source/Plugin/P103_Device_EC.png b/docs/source/Plugin/P103_Device_EC.png new file mode 100644 index 0000000000..f68c3220e0 Binary files /dev/null and b/docs/source/Plugin/P103_Device_EC.png differ diff --git a/docs/source/Plugin/P103_Device_EC_Calibration.png b/docs/source/Plugin/P103_Device_EC_Calibration.png new file mode 100644 index 0000000000..3809304f0a Binary files /dev/null and b/docs/source/Plugin/P103_Device_EC_Calibration.png differ diff --git a/docs/source/Plugin/P103_Device_HUM.png b/docs/source/Plugin/P103_Device_HUM.png new file mode 100644 index 0000000000..7bd7d3b2d4 Binary files /dev/null and b/docs/source/Plugin/P103_Device_HUM.png differ diff --git a/docs/source/Plugin/P103_Device_HUM_Options.png b/docs/source/Plugin/P103_Device_HUM_Options.png new file mode 100644 index 0000000000..ea727f8c11 Binary files /dev/null and b/docs/source/Plugin/P103_Device_HUM_Options.png differ diff --git a/docs/source/Plugin/P103_Device_HUM_Values.png b/docs/source/Plugin/P103_Device_HUM_Values.png new file mode 100644 index 0000000000..926054d61e Binary files /dev/null and b/docs/source/Plugin/P103_Device_HUM_Values.png differ diff --git a/docs/source/Plugin/P103_Device_ORP.png b/docs/source/Plugin/P103_Device_ORP.png new file mode 100644 index 0000000000..e760cf7091 Binary files /dev/null and b/docs/source/Plugin/P103_Device_ORP.png differ diff --git a/docs/source/Plugin/P103_Device_ORP_Calibration.png b/docs/source/Plugin/P103_Device_ORP_Calibration.png new file mode 100644 index 0000000000..eafe628803 Binary files /dev/null and b/docs/source/Plugin/P103_Device_ORP_Calibration.png differ diff --git a/docs/source/Plugin/P103_Device_pH.png b/docs/source/Plugin/P103_Device_pH.png new file mode 100644 index 0000000000..389477d8c0 Binary files /dev/null and b/docs/source/Plugin/P103_Device_pH.png differ diff --git a/docs/source/Plugin/P103_Device_pH_Calibration.png b/docs/source/Plugin/P103_Device_pH_Calibration.png new file mode 100644 index 0000000000..2dbcb770fc Binary files /dev/null and b/docs/source/Plugin/P103_Device_pH_Calibration.png differ diff --git a/docs/source/Plugin/P105.rst b/docs/source/Plugin/P105.rst index 49c21d21a8..c28fc651d0 100644 --- a/docs/source/Plugin/P105.rst +++ b/docs/source/Plugin/P105.rst @@ -67,11 +67,17 @@ 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. +* **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. +* **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. +* **AHT21** An more modern version of the sensor, very similar to the AHT20, in a more compact chip package. + +When selecting the **AHT1x** Sensor model, an extra option is made available: + +.. image:: P105_AHT10_alt_init.png + +* **AHT10 Alternative initialization**: Some AHT10 clone sensors do not seem to like the regular AHT10/AHT15 initialization sequence. They do however accept a soft reset command. By enabling this checkbox, only the soft reset is sent to the device. Only available for AHT1x devices. Data Acquisition ^^^^^^^^^^^^^^^^ @@ -92,4 +98,6 @@ Change log .. versionchanged:: 2.0 ... + |changed| 2024-12-03 Add alternative initialization option + |added| 2021-08-01 Moved from ESPEasy PluginPlayground to the main repository. diff --git a/docs/source/Plugin/P105_AHT10_alt_init.png b/docs/source/Plugin/P105_AHT10_alt_init.png new file mode 100644 index 0000000000..f74ee299b4 Binary files /dev/null and b/docs/source/Plugin/P105_AHT10_alt_init.png differ diff --git a/docs/source/Plugin/P159.rst b/docs/source/Plugin/P159.rst index 70183da070..f754d4b23a 100644 --- a/docs/source/Plugin/P159.rst +++ b/docs/source/Plugin/P159.rst @@ -137,9 +137,9 @@ After checking the checkbox to enabled state, the settings will be available imm * **Idle seconds**: The number of seconds the *Presence* stays active after presence is removed, can be set here. Default value 5 sec. max. value is 65535 sec. * **Max. Moving gates**: The number of active gates for detecting Moving presence. Range 2 .. 8. * **Max. Stationary gates**: The number of active gates for detecting Stationary presence. Range 2 .. 8. -* **Sensitivity, Gate 0 .. 8**: For each type of detection, the sensitivity treshold can be set, range 0 .. 100, where 0 is the most sensitive, and 100 means it won't trigger, as that's the max. value that will be reported. +* **Sensitivity, Gate 0 .. 8**: For each type of detection, the sensitivity treshold can be set, range 0 .. 101, where 0 is the most sensitive, and 101 means it won't trigger, as 100 is the max. value that will be reported. -For each gate the distance range in meters is also shown. When the highest enabled Gate is less that the default 8, then only up to that gate-number is shown and configurable. +For each gate the distance range in meters is also shown. When the highest enabled Gate is less than the default 8, then only up to that gate-number is shown and configurable. If the **Modify sensor settings** checkbox is checked when submitting the page, the settings are sent to the sensor, and the sensor will be restarted to activate them. The configured values are persistently stored in the LD2410 sensor. diff --git a/docs/source/Plugin/P175.rst b/docs/source/Plugin/P175.rst new file mode 100644 index 0000000000..a164346f16 --- /dev/null +++ b/docs/source/Plugin/P175.rst @@ -0,0 +1,279 @@ +.. include:: ../Plugin/_plugin_substitutions_p17x.repl +.. _P175_page: + +|P175_typename| +================================================== + +|P175_shortinfo| + +Plugin details +-------------- + +Type: |P175_type| + +Port Type: |P175_porttype| + +Name: |P175_name| + +Status: |P175_status| + +GitHub: |P175_github|_ + +Maintainer: |P175_maintainer| + +Used libraries: |P175_usedlibraries| + +Shared code +----------- + +.. note:: Because of the technical overlap with other Plantower dust sensors, this plugin shares most code and documentation with :ref:`p053_page`, that's why you'll also see some information or selections related to these, very similar, Plantower dust sensors. + +.. include:: P053_P175_common.repl + +Supported hardware +------------------ + +The supported Plantower device is the PMSA003i, as no other Plantower dust sensors using an I2C interface are currently available. + +PMSA003i: + +.. image:: P175_PMSA003i.png + +Precautions +----------- + +The PMSx003 run on 5V. All inputs and outputs are TTL 3.3V compatible so no level converter is needed. + +Some boards come with a sweep-up circuit to convert 3.3V to 5V, and can also be powered with 3.3V. + +Pins: + +.. code-block:: none + + VCC - 5V (for fan and internal logic) + GND - Ground (Note that chassis/case are ground also) + SDA/SCL - 3V3 I2C Data and clock signal + SET - Standby function, when pulled down the module does not send information and goes into a low power state. + RESET - Reset the module, similar to power-up, it takes ~30 seconds before data is received + + +Configuration +------------- + +.. image:: P175_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 I2C settings here depend on the build used. At least the **Force Slow I2C speed** option is available. This sensor can also be used with an I2C Multiplexer. For details see the :ref:`Hardware_page`. + +According to the documentation, the max. communication speed for this sensor is 100 kHz, the default Slow I2C speed setting, so this option is enabled by default. + +Device Settings +^^^^^^^^^^^^^^^ + +* **GPIO -> RST(optional)**: The pin to control the Reset signal. Not used when set to None. + +* **GPIO -> SET(optional)**: The pin to control the Active/Sleep state. Not used when set to None. + + +Device +^^^^^^ + +* **Sensor model**: Fixed value **PMSA003i**, not changeable at this time. + +Output +^^^^^^ + +Output values +""""""""""""" + +With PMSA003i extra output values are available. To choose which values are made available in the task, this combobox provides the available options. + +.. note:: Changing this output selector will toggle a reload of the page. When the output selection has changed, the task value names will be reset to their (new) default names and the nr. of decimals will be set to proper values. (e.g. 1 decimal for temp/hum and 3 decimals for Formaldehyde) The nr of decimals will be set to at least 1 when oversampling is enabled. + +Available options: + +.. image:: P053_OutputValuesOptions.png + +* *Particles µg/m3: pm1.0, pm2.5, pm10*: The default output values, available for all supported sensors. + +- ``PM1.0`` - Concentration of particles < 1 micron (µg/m3) +- ``PM2.5`` - Concentration of particles < 2.5 micron (µg/m3) +- ``PM10`` - Concentration of particles < 10 micron (µg/m3) + +* *Particles µg/m3: pm2.5; Other: Temp, Humi, HCHO (PMS5003ST)*: Particles > 2.5 micron (µg/m3) (**only** supported by the PMS5003ST sensor). + +- ``PM2.5`` - Concentration of particles < 2.5 micron (µg/m3) +- ``Temp`` - Temperature +- ``Humi`` - Humidity +- ``HCHO`` - Formaldehyde concentration measurement (Formula: CH\ :sub:`2`\ O, or H-CHO) + +Two choices for particle counts in *count/0.1L* (PMS1003/5003(ST)/7003/A003i) : + +* *Particles count/0.1L: cnt1.0, cnt2.5, cnt5, cnt10*: + +* *Particles count/0.1L: cnt0.3, cnt0.5, cnt1.0, cnt2.5*: + +With: + +- ``cnt0.3`` - Count of particles > 0.3 micron per 0.1L of air +- ``cnt0.5`` - Count of particles > 0.5 micron per 0.1L of air +- ``cnt1.0`` - Count of particles > 1 micron per 0.1L of air +- ``cnt2.5`` - Count of particles > 2.5 micron per 0.1L of air +- ``cnt5`` - Count of particles > 5 micron per 0.1L of air +- ``cnt10`` - Count of particles > 10 micron per 0.1L of air + +.. image:: P053_OutputValuesCnt.png + +.. note:: ``PMxx`` values relate to particles **less than or equal** to said size, while count/100ml relates to particles of **at least** said size. + Except when "Split count bins" is checked, then the "count/0.1L" values represent only a single bin. + + +Events for non-output values +"""""""""""""""""""""""""""" + +When an option other than **None** is selected, the **Output values** that are not directly available, will be sent via events. +If there is some overlap in selected output values and the extra event selector, only those values which were not already sent as regular task values, will be sent in extra events. + +.. note:: The "Single event with all values" option only combines the 4 selected task values in 1 event. Extra events will only contain 1 value per event. + + +Available options: + +.. image:: P053_EventOptions.png + +* *Particles µg/m3 and Temp/Humi/HCHO*: + +When *Particles µg/m3: pm1.0, pm2.5, pm10* is selected: ``#Temp``, ``#Humi`` and ``#HCHO``, with the measured value available in ``%eventvalue1%``. (Not available for PMSA003i) + +When *Particles µg/m3: pm2.5; Other: Temp, Humi, HCHO (PMS5003ST)* is selected: ``#pm1.0`` and ``#pm10``. + +* *Particles µg/m3, Temp/Humi/HCHO and Particles count/0.1L*: + +All of the above, and also ``#pm2.5``, ``#cnt1.0``, ``#cnt2.5`` and ``#cnt10`` events are generated if these are not selected as **Output values**. + +These events can be used to store the values in a Dummy Device, so they can be sent out using a Controller, or they can be directly sent to an external system. + +Example: (Sensor device using model PMSA003i and Dummy device named ``Particles`` with 2 values named ``pm1.0`` and ``pm10``) + +.. code-block:: none + + On PMSA003i#pm1.0 do + TaskValueSet,Particles,pm1.0,%eventvalue1% + Endon + On PMSA003i#pm10 do + TaskValueSet,Particles,pm10,%eventvalue1% + Endon + +These events will *only* be generated when the **Rules** option is enabled on the Tools/Advanced page. + +Data Processing +^^^^^^^^^^^^^^^ + +The PMSx003 sensors may output samples quite often. +Typically a sample is sent every 800 msec, with shorter intervals when the data does change a lot between readings. +However, the sensor itself does not always have new data when a packet is sent by the sensor. +These duplicate messages are detected and ignored. + +* **Sensor init time after wake**: + +The Plantower datasheet suggests to let the sensor run for at least 30 seconds after power on (or wake up) to get a reliable reading. + +When set to a value over 0 seconds, a timer will be set when the sensor is called to wakeup. +During this period, any received sample will be ignored. + +If running the sensor at an interval to save energy consumption and extend the sensors lifetime, make sure the "active" duration is longer than this sensor init time. +The sensor typically needs 2.3 seconds to complete a measurement. + +So a good duration for wake time is at least 35 - 40 seconds (oversampling enabled). + + +* **Oversampling**: + +By default, only the last sample is output by the task. +But since the counted values may change quite a lot between samples, it is advised to enable oversampling. +With oversampling enabled, the reported values are averaged over the period between calls of ``PLUGIN_READ`` (Interval). +This may give a more stable output value to process. + +The default nr of decimals will be set to 1 when oversampling is enabled. (may require to switch the output values combo box) + +.. note:: When putting the sensor to sleep, any collected data in the averaging buffer is flushed by scheduling a ``PLUGIN_READ``. This will output the data to any connected controller and generate the appropriate events. + Any data still present in the buffer when waking the sensor is flushed, to make sure no old and new data is merged. + +* **Split count bins**: + +The "count/0.1L" values are based on particles with at least the given size. +Thus a ``cnt0.3`` value describes all particles with a size of at least 0.3 micron. + +In some use cases it can be useful to count only the particles of a specific size, like 0.3 ... 0.5 micron. +When "Split count bins" is checked, the recorded counted values will be split over single bins. + + +Lifetime Helper +^^^^^^^^^^^^^^^^ + +The laser diode inside the PMSx003 has a lifetime of about 8000 h, nearly one year. With the actual plugin the sensor is powered permanently so we have to take some care about this. + +wake/sleep command +"""""""""""""""""" + +Using the ``pmsx003,sleep`` and ``pmsx003,wake`` commands can be used to reduce the energy consumption and extend the laser lifetime. + +Example rules: + +.. code-block:: none + + On System#Boot do //When the ESP boots, do + looptimerset,1,300 // Start loop timer 1, 300 sec interval + timerSet,2,30 // Set timer 2 to put the sensor to sleep again + endon + + On Rules#Timer=1 do + timerSet,2,30 // Set timer 2 to put the sensor to sleep again + pmsx003,wake + endon + + On Rules#Timer=2 do + pmsx003,sleep + endon + +In the example setup, a GPIO pin should be connected to the ``SET`` input of the PMSA003i. If it is pulled low the sensor sleeps. The ``wake`` and ``sleep`` commands change the state of the configured GPIO pin accordingly. + +Unlike the serial connected PMSx003 sensors, no sleep/wake command can be sent to the sensor, so sleep/wake can only be achieved by using the **SET** pin. + + +Commands available +^^^^^^^^^^^^^^^^^^ + +.. include:: P175_commands.repl + +Events +^^^^^^ + +A task running the PMSx003 can be configured to output a number of values as standard task values. +However the sensor outputs more values than can be used as ESPEasy task values. + +To overcome this limitation, one can set what other measured values can be useful to have as an event for processing in the rules. + +Which of the following events may be sent, depends on this setting and also whether the sensor is capable of measuring the described unit of measure. + +.. include:: P053_events.repl + +Change log +---------- + +.. versionadded:: 2.0 + ... + + |added| + 2024-10-12 Initial release version. + + + + + diff --git a/docs/source/Plugin/P175_DeviceConfiguration.png b/docs/source/Plugin/P175_DeviceConfiguration.png new file mode 100644 index 0000000000..66e5bf30f2 Binary files /dev/null and b/docs/source/Plugin/P175_DeviceConfiguration.png differ diff --git a/docs/source/Plugin/P175_PMSA003i.png b/docs/source/Plugin/P175_PMSA003i.png new file mode 100644 index 0000000000..ff76f6c2ba Binary files /dev/null and b/docs/source/Plugin/P175_PMSA003i.png differ diff --git a/docs/source/Plugin/P175_commands.repl b/docs/source/Plugin/P175_commands.repl new file mode 100644 index 0000000000..eff5338618 --- /dev/null +++ b/docs/source/Plugin/P175_commands.repl @@ -0,0 +1,22 @@ +.. csv-table:: + :header: "Command", "Extra information" + :widths: 20, 30 + + " + ``pmsx003,wake`` + + "," + Pulls the ``SET`` pin high, to wake the sensor. + " + " + ``pmsx003,sleep`` + + "," + Pulls the ``SET`` pin low, so the sensor will go in sleep mode. + " + " + ``pmsx003,reset`` + + "," + If the ``RST`` pin is set, the pin will be pulled down for 250 msec to reset the sensor. + " diff --git a/docs/source/Plugin/_Plugin.rst b/docs/source/Plugin/_Plugin.rst index 0199448d7a..e64f796ed8 100644 --- a/docs/source/Plugin/_Plugin.rst +++ b/docs/source/Plugin/_Plugin.rst @@ -399,6 +399,7 @@ There are different released versions of ESP Easy: ":ref:`P170_page`","|P170_status|","P170" ":ref:`P172_page`","|P172_status|","P172" ":ref:`P173_page`","|P173_status|","P173" + ":ref:`P175_page`","|P175_status|","P175" .. include:: _plugin_sets_overview.repl diff --git a/docs/source/Plugin/_plugin_categories.repl b/docs/source/Plugin/_plugin_categories.repl index 0881529656..84d8c0efea 100644 --- a/docs/source/Plugin/_plugin_categories.repl +++ b/docs/source/Plugin/_plugin_categories.repl @@ -4,7 +4,7 @@ .. |Plugin_Communication| replace:: :ref:`P016_page`, :ref:`P020_page`, :ref:`P035_page`, :ref:`P044_page`, :ref:`P054_page`, :ref:`P071_page`, :ref:`P087_page`, :ref:`P089_page`, :ref:`P094_page`, :ref:`P101_page`, :ref:`P118_page` .. |Plugin_Display| replace:: :ref:`P012_page`, :ref:`P023_page`, :ref:`P036_page`, :ref:`P057_page`, :ref:`P073_page`, :ref:`P075_page`, :ref:`P095_page`, :ref:`P104_page`, :ref:`P116_page`, :ref:`P131_page`, :ref:`P148_page` .. |Plugin_Distance| replace:: :ref:`P013_page`, :ref:`P110_page`, :ref:`P113_page`, :ref:`P134_page` -.. |Plugin_Dust| replace:: :ref:`P018_page`, :ref:`P053_page`, :ref:`P056_page`, :ref:`P144_page` +.. |Plugin_Dust| replace:: :ref:`P018_page`, :ref:`P053_page`, :ref:`P056_page`, :ref:`P144_page`, :ref:`P175_page` .. |Plugin_Energy_AC| replace:: :ref:`P076_page`, :ref:`P077_page`, :ref:`P078_page`, :ref:`P102_page`, :ref:`P108_page` .. |Plugin_Energy_DC| replace:: :ref:`P027_page`, :ref:`P085_page`, :ref:`P115_page`, :ref:`P132_page` .. |Plugin_Energy_Heat| replace:: :ref:`P088_page`, :ref:`P093_page` diff --git a/docs/source/Plugin/_plugin_substitutions_p04x.repl b/docs/source/Plugin/_plugin_substitutions_p04x.repl index 77494d918d..fb11018a5f 100644 --- a/docs/source/Plugin/_plugin_substitutions_p04x.repl +++ b/docs/source/Plugin/_plugin_substitutions_p04x.repl @@ -15,7 +15,7 @@ .. |P041_type| replace:: :cyan:`Output` .. |P041_typename| replace:: :cyan:`Output - NeoPixel (Word Clock)` .. |P041_porttype| replace:: `.` -.. |P041_status| replace:: :green:`NORMAL` :yellow:`NEOPIXEL` +.. |P041_status| replace:: :yellow:`NEOPIXEL` .. |P041_github| replace:: P041_NeoClock.ino .. _P041_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P041_NeoClock.ino .. |P041_usedby| replace:: `.` @@ -28,7 +28,7 @@ .. |P042_type| replace:: :cyan:`Output` .. |P042_typename| replace:: :cyan:`Output - NeoPixel (Candle)` .. |P042_porttype| replace:: `.` -.. |P042_status| replace:: :green:`NORMAL` :yellow:`NEOPIXEL` +.. |P042_status| replace:: :yellow:`NEOPIXEL` .. |P042_github| replace:: P042_Candle.ino .. _P042_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P042_Candle.ino .. |P042_usedby| replace:: `.` diff --git a/docs/source/Plugin/_plugin_substitutions_p05x.repl b/docs/source/Plugin/_plugin_substitutions_p05x.repl index 5baecc6bbc..22dee3255d 100644 --- a/docs/source/Plugin/_plugin_substitutions_p05x.repl +++ b/docs/source/Plugin/_plugin_substitutions_p05x.repl @@ -53,7 +53,7 @@ .. |P054_name| replace:: :cyan:`DMX512 TX` .. |P054_type| replace:: :cyan:`Communication` .. |P054_typename| replace:: :cyan:`Communication - DMX512 TX` -.. |P054_porttype| replace:: `.` +.. |P054_porttype| replace:: `Serial` .. |P054_status| replace:: :yellow:`COLLECTION` .. |P054_github| replace:: P054_DMX512.ino .. _P054_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P054_DMX512.ino diff --git a/docs/source/Plugin/_plugin_substitutions_p10x.repl b/docs/source/Plugin/_plugin_substitutions_p10x.repl index 87af9e5666..84cc1e7d1b 100644 --- a/docs/source/Plugin/_plugin_substitutions_p10x.repl +++ b/docs/source/Plugin/_plugin_substitutions_p10x.repl @@ -37,16 +37,16 @@ .. |P102_compileinfo| replace:: `.` .. |P102_usedlibraries| replace:: https://github.com/olehs/PZEM004T -.. |P103_name| replace:: :cyan:`Atlas Scientific EZO pH` +.. |P103_name| replace:: :cyan:`Atlas Scientific EZO pH ORP EC DO HUM` .. |P103_type| replace:: :cyan:`Environment` -.. |P103_typename| replace:: :cyan:`Environment - Atlas Scientific EZO pH` +.. |P103_typename| replace:: :cyan:`Environment - Atlas Scientific EZO pH ORP EC DO HUM` .. |P103_porttype| replace:: `.` .. |P103_status| replace:: :yellow:`CLIMATE` -.. |P103_github| replace:: P103_Atlas_EZO_pH.ino -.. _P103_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P103_Atlas_EZO_pH.ino +.. |P103_github| replace:: P103_Atlas_EZO_pH_ORP_EC_DO.ino +.. _P103_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P103_Atlas_EZO_pH_ORP_EC_DO.ino .. |P103_usedby| replace:: `.` .. |P103_shortinfo| replace:: `.` -.. |P103_maintainer| replace:: TD-er +.. |P103_maintainer| replace:: `TD-er tonhuisman` .. |P103_compileinfo| replace:: `.` .. |P103_usedlibraries| replace:: `.` .. |P103_datasheet| replace:: https://atlas-scientific.com/files/pH_EZO_Datasheet.pdf diff --git a/docs/source/Plugin/_plugin_substitutions_p17x.repl b/docs/source/Plugin/_plugin_substitutions_p17x.repl index 70c68bb46f..68a5ffe318 100644 --- a/docs/source/Plugin/_plugin_substitutions_p17x.repl +++ b/docs/source/Plugin/_plugin_substitutions_p17x.repl @@ -36,3 +36,16 @@ .. |P173_maintainer| replace:: `tonhuisman` .. |P173_compileinfo| replace:: `.` .. |P173_usedlibraries| replace:: `.` + +.. |P175_name| replace:: :cyan:`PMSx003i (I2C)` +.. |P175_type| replace:: :cyan:`Dust` +.. |P175_typename| replace:: :cyan:`Dust - PMSx003i (I2C)` +.. |P175_porttype| replace:: `I2C` +.. |P175_status| replace:: :yellow:`CLIMATE` +.. |P175_github| replace:: P175_PMSx003i.ino +.. _P175_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_P175_PMSx003i.ino +.. |P175_usedby| replace:: `.` +.. |P175_shortinfo| replace:: `.` +.. |P175_maintainer| replace:: `.` +.. |P175_compileinfo| replace:: `.` +.. |P175_usedlibraries| replace:: `.` diff --git a/docs/source/Reference/Command.rst b/docs/source/Reference/Command.rst index afb01a2bcd..ef27287ee5 100644 --- a/docs/source/Reference/Command.rst +++ b/docs/source/Reference/Command.rst @@ -825,6 +825,11 @@ P169 :ref:`P169_page` .. include:: ../Plugin/P169_commands.repl +P175 :ref:`P175_page` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: ../Plugin/P175_commands.repl + .. .. *** Insert regular plugin commands above this remark! *** .. _AdafruitGFX Helper commands: diff --git a/docs/source/Reference/Events.rst b/docs/source/Reference/Events.rst index 32b31a804a..c49826b329 100644 --- a/docs/source/Reference/Events.rst +++ b/docs/source/Reference/Events.rst @@ -559,3 +559,8 @@ P170 :ref:`P170_page` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: ../Plugin/P170_events.repl + +P175 :ref:`P175_page` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../Plugin/P053_events.repl diff --git a/src/_C002.cpp b/src/_C002.cpp index 1645866698..dc9f9f13bd 100644 --- a/src/_C002.cpp +++ b/src/_C002.cpp @@ -110,7 +110,7 @@ bool CPlugin_002(CPlugin::Function function, struct EventStruct *event, String& switch (Settings.getPluginID_for_task(x).value) { case 1: // temp solution, if input switch, update state { - action = strformat(F("gpio,%d,%d"), x, static_cast(nvalue)); + action = strformat(F("gpio,%d,%d"), Settings.TaskDevicePin1[x], static_cast(nvalue)); break; } case 29: // temp solution, if plugin 029, set gpio diff --git a/src/_P021_Level.ino b/src/_P021_Level.ino index 0635d6926d..3453edfa19 100644 --- a/src/_P021_Level.ino +++ b/src/_P021_Level.ino @@ -4,8 +4,12 @@ // ####################################################################################################### // #################################### Plugin 021: Level Control ######################################## // ####################################################################################################### +// Digital output controller based upon a analog input compared with a setpoint with hysteresis +// Original intention to control a level by opening a valve or switching a pump +// Extended by timer based state control to support pumps with additional requirements (floor heating ciculation pump) // Changelog: +// 2024-07-07, flashmark: Reworked to support floor heating pump (added state machine control) // 2023-03-13, tonhuisman: Add setting to invert the Output state // 2022-08-22, tonhuisman: Add setting to auto-save a changed setting after x minutes, size optimizations, add PCONFIG defines // 2021-12-29, tonhuisman: Add setting to enable/disable saving the settings when the Set Level value is changed using the config @@ -14,28 +18,189 @@ // cleanup source, prevent crashing when hysteresis is 0.0, run Uncrustify source formatter, // apply float/double math compare functions instead of regular comparisons +// NOTE: Due to lack of flash memory for most ESP8266 builds the extensions are only available on a limited set of builds. +// Code size and functionality is controlled by several build flags: +// PLUGIN_021_DEBUG When defined: Additional debugging available for logging and webform +// P021_MIN_BUILD_SIZE When defined: Leave out some less important functionality +// FEATURE_P021_EXTRAS 0 : No additional functionality +// 1 : New functionality per change 2024-07-07 +// > : Reserved for future functionality improvements +// Debugging is expected to be switched off when build size is limited by the other flags +// Minimum build size is expected to be true when extras >=1 +////////////////////////////////////////////////////////////////////////////////////////////////////////// + # include "src/Helpers/ESPEasy_math.h" # include "src/Globals/RulesCalculate.h" # include "src/WebServer/ESPEasy_WebServer.h" +//// #define LIMIT_BUILD_SIZE +# define PLUGIN_021_DEBUG + +// For additional debugging information use PLUGIN_021_DEBUG (see note) +# ifdef BUILD_NO_DEBUG +# undef PLUGIN_021_DEBUG +# else // ifdef BUILD_NO_DEBUG +////# define PLUGIN_021_DEBUG +# endif // ifndef/else BUILD_NO_DEBUG + +// See note at top of file +# ifdef LIMIT_BUILD_SIZE +# define FEATURE_P021_EXTRAS 0 +# define P021_MIN_BUILD_SIZE +# undef PLUGIN_021_DEBUG +# else // ifdef LIMIT_BUILD_SIZE +# define FEATURE_P021_EXTRAS 1 +# endif // ifdef LIMIT_BUILD_SIZE + # define PLUGIN_021 # define PLUGIN_ID_021 21 # define PLUGIN_NAME_021 "Regulator - Level Control" # define PLUGIN_VALUENAME1_021 "Output" +# define PLUGIN_VALUENAME2_021 "State" + +# define P021_GPIO_RELAY CONFIG_PIN1 + +// Define the configuration options using ESPeasy standard structures +// For unique identification on the HTML form use P021_GUID_