ESPEasy/docs/source/Plugin/P033.rst

.. include:: ../Plugin/_plugin_substitutions_p03x.repl
.. _P033_page:

|P033_typename|
==================================================

|P033_shortinfo|

Plugin details
--------------

Type: |P033_type|

Name: |P033_name|

Status: |P033_status|

GitHub: |P033_github|_

Maintainer: |P033_maintainer|

Used libraries: |P033_usedlibraries|

Description
------------

You can use a special dummy device within ESP Easy to provide additional features to the rules engine. A dummy device contains 1 (Single) to 4 (Quad) sensor values, depending on the Output Data Type selected, that can be used as variables to store custom numerical data. (floating point values, like 123.50)

The dummy device can be used like any other sensor to send it's data to a Controller. But this is not mandatory if you only want to use it within your own rules section.

Dummy tasks can be used like temporary variables to store data.
One nice benefit is that these task values of Dummy tasks are also kept in RTC memory.
So these may survive a reboot, as long as the ESP remains powered.

Device Configuration
--------------------

.. image:: P033_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.


Storing Values
--------------

Typically, one can only interact with a Dummy task via the ``TaskValueSet`` command:

.. code-block:: none

  TaskValueSet <task nr/task name>,<value nr/value name>,<value|formula>

A few examples:

You run your dummy device from task number 3 and the first value should contain something calculated from a temperature sensor labeled "Outdoor":

.. code-block:: none

  TaskValueSet 3,1,[Outdoor#Temperature]-10

To make the variable to set and the task number independent, the name of the task and/or value can be used instead of the numbers. 

So for a Dummy device named ``Dummy``, Output Data Type set to Temp / Hum, and Values named ``Temp`` and ``Hum``, setting the Temperature value:

.. code-block:: none

  TaskValueSet,Dummy,temp,[Outdoor#Temperature]-10

(task name and value name are not case sensitive)

Note: You can use multiple Dummy devices if needed!

Output Configuration
--------------------

A Dummy can be configured to output a specific data type.
Especially Domoticz controllers require some specific data type to properly handle specific devices which output several units of measure.

For example "Temp / Hum / Baro" are obviously intended to mimic the well known Bosch BME280 sensor.

Basic data types like "Single", "Dual", "Triple", "Quad" are intended to set resp. 1 ... 4 ``float`` values.

This selector is using a categorized display when the build includes this enhanced selector (ESP32 only):

.. image:: P033_OutputDataTypeOptions.png

Available options, grouped per category:

**Basic**: ``Single, Dual, Triple, Quad``

**Environment**: ``Temp¹, Hum¹, Baro¹, Wind¹``

**Other**: ``Switch¹, Dimmer, String, UInt32 (1x), UInt32 (2x), UInt32 (3x), UInt32 (4x),`` ``Int32 (1x), Int32 (2x), Int32 (3x), Int32 (4x), UInt64 (1x), UInt64 (2x),`` ``Int64 (1x), Int64 (2x), Double (1x), Double (2x)``

Value Types marked with ``¹`` are supported for use in MQTT AutoDiscovery.


Extended Output Data Types
^^^^^^^^^^^^^^^^^^^^^^^^^^

Added: 2023/04/15

Storing data in ``float`` values may result in loss of decimals.
A float can only store upto 22 bit if numerical information.

For example the "UnixTime" (number of seconds since 1970/01/01) cannot accurately be stored in a float.

To overcome these issues, a number of integer types are added:

* Int32  - Integer value ranging from ``-2147483648`` ... ``2147483647`` (-1 * 2^31 ... (2^31 - 1))
* UInt32 - Integer value ranging from ``0`` ... ``4294967295`` (2^32 - 1) 
* Int64  - Integer value ranging from -1 * 2^63 ... (2^63 - 1)
* UInt64 - Integer value ranging from 0 ... (2^64 - 1)
* Double - "Double" Floating point value capable of storing 52 bit of numerical information.

The offered selection also shows the number of task values being configured.
For example ``Int32 (3x)`` implies 3 task values of type ``Int32``.

Since 64 bit ints and double need 8 bytes, where the other types only require 4 bytes.
Therefore the maximum number of those task values possible is half that of the other types.

Storing data in 64 bit ints may not allow to store the full range as one may expect to store based on the integer types.
The ``TaskValueSet`` command internally processes data as ``double``, thus limiting the maximum range of these integer values to -9007199254740992 ... 9007199254740991.

One can store larger values in these 64 bit int types, but this will result in loss of bits.

For example: 

* ``9007199254740993`` cannot be stored in such a data type as it will be rounded back to ``9007199254740992`` when used.
* ``1234567890123456789`` will be read back as ``1234567890123456768``, which may seem correct at first sight, but the last few digits are wrong.

Storing large values in other integer types, like ``UInt32``, will be clipped to the maximum value that can be handled by that type.

For example:

* ``1234567890123456789`` stored in an ``UInt32`` will be read back as ``4294967295``
* ``-1`` stored in an ``UInt32`` will be read back as ``4294967295``
* ``1234567890123456789`` stored in an ``Int32`` will be read back as ``2147483647``
* ``-1`` stored in an ``Int32`` will be read back as ``-2147483648``



.. include:: DataAcquisition.repl

In ESPEasy, a task can be triggered to yield some new sample data.
For other plugins, this means the sensor is read and when successful there is some new data to process.

However, since the Dummy device doesn't interact with a device, it will always be "successful" on a task run.

One may set the "Interval" to periodically trigger a new task run, or trigger a task run via the command ``TaskRun``.

.. note:: The command ``TaskValueSetAndRun`` is a combination of ``TaskValueSet`` and ``TaskRun``.

On a task run, there will be one or more events fired (depending on whether or not "Single event with all values" is checked).
And all connected controllers of that task will be handed over the values present in the task values.

Especially Domoticz controllers are very specific to the output data type.

Values
^^^^^^

The plugin provides the ``Dummy`` value, that can be changed to the desired name. 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>`


.. Supported hardware
.. ------------------

.. .. |P033_usedby|

.. Commands available
.. ^^^^^^^^^^^^^^^^^^

.. .. include:: P033_commands.repl

.. Events
.. ~~~~~~

.. .. include:: P033_events.repl

Change log
----------

.. versionchanged:: 2.0
  ...

  |improved|
  2025-07-17 Add categorized output configuration (ESP32 only)

  |improved|
  2023-04-15 Add more types of task values, like (u)int32, (u)int64 and double.

  |improved|
  2021-08-18 Make Interval optional, so no interval (0) can be used.

  |added|
  Major overhaul for 2.0 release.

.. versionadded:: 1.0
  ...

  |added|
  Initial release version.