ESPEasy/docs/source/Plugin/P000_commands.repl

**TODO** : Check commands M..Z and check for all commands whether the "class" is still valid.


.. csv-table::
    :header: "Command", "Class", "Purpose / Syntax"
    :widths: 8, 5, 30

    "
    AsyncEvent","
    :blue:`Special`","
    Schedule an event, it's possible to send a float value along as well.

    This is the same as a regular event, but it will not be executed immediately.
    Instead it will be added to an event queue.
    
    Use this to keep rules execution times as short as possible.

    N.B. New values sent by a task will also be of this type.

    See event syntax below..."
    "
    AccessInfo","
    :red:`Internal`","
    Show allowed IP range for the web interface.

    ``AccessInfo``
    
    Example output: ``Allowed IP range : 192.168.10.0 - 192.168.10.255``"
    "
    Background","
    :red:`Internal`","
    Process background tasks.

    ``Background``"
    "
    Build","
    :red:`Internal`","
    Get or set build information.  This will not be stored, so only valid until reboot.

    ``Build``

    ``Build,12345``
    
    Example output: ``Build:20104``"
    "
    ClearAccessBlock","
    :red:`Internal`","
    Clear allowed IP range for the web interface for the current session.
    See also ``AccessInfo``.

    ``ClearAccessBlock``"
    "
    ClearPassword","
    :red:`Internal`","
    Clear the password of the unit.
    See also ``Password``.

    ``ClearPassword,<current password>``"
    "
    ClearRTCram","
    :red:`Internal`","
    Clear all (cached) data from the RTC memory. 
    This data is persistent as long as the node is powered and thus survives a reboot or crash.

    ``ClearRTCram``"
    "
    Config","
    :red:`Internal`","
    Remote config of a task. 
    This allows for actually change the config as stored in the settings for a task.

    The syntax is like ``config,task,<taskname>,<actual config command>``

    Right now only the ``Regulator - Level Control`` plugin (P021) supports this via its ``SetLevel`` command.

    Later other config options might be added, like ``SetInterval`` or other generic options.

    Example for the task named 'VoltageLevel': ``config,task,VoltageLevel,SetLevel,22``"
    "
    ControllerDisable","
    :red:`Internal`","
    Disable a controller.
    This will not save the settings, but if the settings get saved anyway the controller will remain disabled at reboot.

    ``ControllerDisable,<controller nr>``"
    "
    ControllerEnable","
    :red:`Internal`","
    Enable a controller. (Only possible when a protocol is assigned to the controller index)
    This will not save the settings, but if the settings get saved anyway the controller will remain enabled at reboot.

    ``ControllerEnable,<controller nr>``"
    "
    DateTime","
    :red:`Internal`","
    Get or set the date and time (optional).

    Usage: ``Datetime[,YYYY-MM-DD[,hh:mm:ss]]``

    Examples:
    
    * ``Datetime,2020-02-29,00:23:00``
    * ``Datetime,2020-02-29`` - set node time '2020-02-29 00:00:00'
    * ``Datetime`` - get current node time
    
    Time source will be set to ``Manual_set`` until the time will be updated via another source. (e.g. GPS or NTP)"
    "
    Debug","
    :red:`Internal`","
    Change Serial port debug level

    ``Debug,<1-4>``"
    "
    Dec","
    :red:`Internal`","
    Decrement the value of variable n (1..INT_MAX) by 1 or an optional value.

    ``Dec,<n>[,<value>]`` (``value`` = 1 by default)
    
    See also ``Let`` and ``Inc``."
    "
    DeepSleep","
    :red:`Internal`","
    Switch the node to deep sleep.
    Max sleep time depends on library version and differs from roughly 71 minutes (4294 sec.) to 3h46 for ESP8266, and up to 8 years (281474976 sec.) on ESP32 (theoretically).
    If you specify a Min sleep time of 0, you'll have to wake the device yourself by pulling RST to GND. If you specify a negative sleep time value, the maximum will be applied.

    ``DeepSleep,<sleep time in seconds>``"
    "
    Delay","
    :green:`Rules`","
    Delay rule processing. Warning: Do not use this as it may cause all kinds of issues.

    ``Delay,<delay in milliSeconds>``"
    "
    DNS","
    :red:`Internal`","
    Get or set DNS configuration.

    ``DNS``

    ``DNS,8.8.8.8``
    
    Example output: ``DNS:192.168.88.1(DHCP)``"
    "
    DST","
    :red:`Internal`","
    Get or set Daylight Saving Time.

    ``DST``

    ``DST,0`` to disable, ``DST,1`` to enable
    
    Example output: ``DST:true``"
    "
    EraseSDKwifi","
    :red:`Internal`","
    Erase WiFi settings that may have been stored in the SDK wifi settings area.

    ``EraseSDKwifi``"
    "
    Event","
    :blue:`Special`","
    Create an event, it's possible to send a float value along as well.

    See event syntax below..."
    "
    ExecuteRules","
    :red:`Internal`","
    Execute the rules in a specific file on the file system.    

    ``ExecuteRules,<filename>``"
    "
    Gateway","
    :red:`Internal`","
    Get or set the gateway configuration

    ``Gateway``

    ``Gateway,192.168.1.1``
    
    Example output: ``Gateway:192.168.10.254(DHCP)``"
    "
    I2Cscanner","
    :red:`Internal`","
    Run I2C scanner to find connected I2C chips. Output will be sent to the serial port.

    ``I2Cscanner``
    
    Example output:

    .. code-block:: none

     4500043 : Info  : Command: i2cscanner
     I2C  : Found 0x3c
     I2C  : Found 0x40
     I2C  : Found 0x5a

    "
    "
    Inc","
    :red:`Internal`","
    Increment the value of variable n (1..INT_MAX) by 1 or an optional value.

    ``Inc,<n>[,<value>]`` (``value`` = 1 by default)
    
    See also ``Let`` and ``Dec``."
    "
    IP","
    :red:`Internal`","
    Get or set IP address

    ``IP``

    ``IP,<IP address>``
    
    Example output: ``IP:192.168.10.86(DHCP)``"
    "
    Let","
    :red:`Internal`","
    Set the value of variable n (1..INT_MAX).

    ``Let,<n>,<value>``
    
    See also ``Inc`` and ``Dec``."
    "
    Load","
    :red:`Internal`","
    Load (reload) the stored settings.

    ``Load``"
    "
    LogEntry","
    :red:`Internal`","
    Add string to log

    ``LogEntry,<string>[,<level>]``
    
    ``<level>`` is optional and can be any of these (numeric) values:
    
    - 1 = ERROR
    - 2 = INFO (default)
    - 3 = DEBUG
    - 4 = DEBUG_DEV
    
    When a ``<level>`` is provided, it will be present in the log output if the 'Tolerant last parameter' Advanced setting is enabled."
    "
    LogPortStatus","
    :red:`Internal`","
    Display status information about all ports

    ``LogPortStatus``"
    "
    LoopTimerSet

    LoopTimerSet_ms","
    :green:`Rules`","
    Start a sequence of timed events

    * ``LoopTimerSet,<timernr>,<timeInSeconds>``
    * ``LoopTimerSet_ms,<timernr>,<time in msec>``
    * ``LoopTimerSet,<timernr>,<timeInSeconds>,<nr of loops>``
    * ``LoopTimerSet_ms,<timernr>,<time in msec>,<nr of loops>``
    * ``LoopTimerSet,<timernr>,0`` (disables the timer)

    The 3rd value is optional and can be used to set a fixed number of loops.

    When possible, try using the ``LoopTimerSet`` funxtion (or its msec equivalent) to get a consistent schedule interval.
    A loop timer is basing its next scheduled time on the previous scheduled time and not the moment when it is actually executed.
    
    On a typical setup, calling ``TimerSet`` from the rules every time a timer has expired, may cause a delay of at least 20 msec.
    The actual jitter introduced here depends on the load of the node and the length of the rules.

    Please note, the execution time in the rules may differ, but as long as a loop timer is used, the scheduled time to run is always a fixed interval from when it was set. (even when a timer interval was missed)

    The ``Rules#Timer`` event generated by a timer has 2 event values. (since build 2020/08/12):

    * ``%eventvalue1%`` has the timer number (1 ... max timer ID)
    * ``%eventvalue2%`` has the loop count for loop timers (since build 2020/08/12)

    See also ``TimerSet``.

    N.B. the timernr is shared between ``TimerSet`` and ``LoopTimerSet``"
    "
    meminfo","
    :red:`Internal`","
    Will send summary of struct sizes to the serial port.

    ``meminfo``
    
    Example output:

    .. code-block:: none

     4306250 : Info  : Command: meminfo
     SecurityStruct         | 593      
     SettingsStruct         | 1228
     ExtraTaskSettingsStruct| 472 
     DeviceStruct           | 12

    "
    "
    meminfoDetail","
    :red:`Internal`","
    Will enable extra detailed information on the internal structure of the settings file.
    This is displayed graphically in the system info page.
    This state is not stored, so only active until reboot.

    A detailed summary is also sent to the serial port.

    ``meminfoDetail``"
    "
    Name","
    :red:`Internal`","
    Set the name of the unit

    ``Name,<new name>``"
    "
    Password","
    :red:`Internal`","
    Set the password of the unit.
    See also ``ClearPassword``.

    ``Password,<new password>``"
    "
    PostToHTTP","
    :green:`Rules`","
    *Syntax format 1:*

    ``PostToHTTP,[<user>:<password>@]<host>,<port>,<uri>,[<headers>][,<postdata>]``

    Post a command to other network device via HTTP using the http ``POST`` method.

    ``<host>`` can be either a domain name or IP address.

    ``<port>`` is the port to connect to, usually 80 for a HTTP site.

    ``<uri>`` the path on the server to post the message to.

    *Syntax format 2:*

    ``PostToHTTP,http://[<user>:<password>@]<url>,[<headers>][,<postdata>]``

    ``<url>`` is the full hostname (or IP address) and path on the server to post the content to.

    *For both syntax formats:*

    ``<user>`` is an optional user to supply for Basic authentication.

    ``<password>`` is an optional password to supply for Basic authentication.

    ``<headers>`` when provided will be added to the header of the ``POST`` message, has to be in ``<name>:<value>`` format. Can be used to supply a ``Authorization: Bearer <token>`` and/or ``api-key:<key>`` (instead of a user/password Basic authentication) and a ``Content-Type: <content-type>``. Multiple entries have to be separated by a NewLine (``%LF%``) to be processed correctly. When not used (empty) and ``<postdata>`` *is used*, the comma should still be included!

    ``<postdata>`` is the optional content to include in the ``POST`` message. Can be anything, f.e. a JSON formatted string, like in the example below.

    Syntax examples:

    ``PostToHTTP,<host>,<Portnumber>,<uri>,[<headers>][,<postdata>]``

    ``PostToHTTP,<user>:<pass>@<host>,<Portnumber>,<uri>,[<headers>][,<postdata>]``

    ``PostToHTTP,http://<host>/<url>,[<headers>][,<postdata>]``

    ``PostToHTTP,http://<user>:<pass>@<host>/<url>,[<headers>][,<postdata>]``

    ``PostToHTTP,http://<host>:<Portnumber>/<url>,[<headers>][,<postdata>]``
    
    ``PostToHTTP,http://<user>:<pass>@<host>:<Portnumber>/<url>,[<headers>][,<postdata>]``

    Example using syntax format 1:

    ``PostToHTTP,user:password@192.168.1.100,8888,/someurl,'header1:value1%LF%header2:value2,`{'this':{'string':'can','be':'JSON','data':{'one':1,'two':2.0,'bool':true}}}```

    Example using syntax format 2:

    ``PostToHTTP,http://user:password@192.168.1.100:8888/someurl,'header1:value1%LF%header2:value2,`{'this':{'string':'can','be':'JSON','data':{'one':1,'two':2.0,'bool':true}}}```
    
    On completion of the command, the returned status code can be handled in a generated event, f.e. ``http#hostname=404`` for not found error, or ``http#hostname=200`` for success.

    Added: 2023-01-15
    "
    "
    ProvisionConfig","
    :red:`Internal`","
    Fetch ``config.dat`` as configured in the Provisioning configuration (see Settings Archive)

    ``ProvisionConfig``"
    "
    ProvisionSecurity","
    :red:`Internal`","
    Fetch ``security.dat`` as configured in the Provisioning configuration (see Settings Archive)

    ``ProvisionSecurity``"
    "
    ProvisionNotification","
    :red:`Internal`","
    Fetch ``notification.dat`` as configured in the Provisioning configuration (see Settings Archive)

    ``ProvisionNotification``"
    "
    ProvisionProvision","
    :red:`Internal`","
    Fetch ``provisioning.dat`` as configured in the Provisioning configuration (see Settings Archive)

    ``ProvisionProvision``"
    "
    ProvisionRules","
    :red:`Internal`","
    Fetch ``rulesN.txt`` as configured in the Provisioning configuration (see Settings Archive)

    ``ProvisionRules,1`` to fetch ``rules1.txt`` "
    "
    Publish","
    :green:`Rules`","
    Send command using MQTT broker service

    ``Publish,<topic>,<value>``"
    "
    Reboot","
    :red:`Internal`","
    Reboot the ESP

    ``Reboot``"
    "
    Reset","
    :red:`Internal`","
    Reset config to factory default. Caution, all settings will be lost!

    ``Reset``"
    "
    Reset Flash Write Counter","
    :red:`Internal`","
    Reset flash write to zero.

    ``ResetFlashWriteCounter``"
    "
    Rules","
    :red:`Internal`","
    Rules enabled (1) or rules disabled (0)

    ``Rules,<1/0>``"
    "
    Save","
    :red:`Internal`","
    Save config to persistent flash memory

    ``Save``"
    "
    SendTo","
    :green:`Rules`","
    Send command to other ESP (using UDP)

    ``SendTo,<unit nr>,<command>``
    
    If the ``<command>`` contains comma's or spaces, it should be quoted, like ``SendTo,<unit nr>,'<command>'``, the usual quotes can be used, double quotes, single quotes or backticks.
    "
    "
    SendToHTTP","
    :green:`Rules`","
    Send command to other network device using HTTP (not HTTPS!)

    ``<host>`` can be either domain name or IP.

    ``<uri>`` is everything after the ``<host>`` in a normal url. 

    Syntax:

    ``SendToHTTP,<host>,<Portnumber>,<uri>``

    ``SendToHTTP,<user>:<pass>@<host>,<Portnumber>,<uri>``  Added: 2022/07/23

    ``SendToHTTP,http://<host>/<url>``  Added: 2022/07/23

    ``SendToHTTP,http://<user>:<pass>@<host>/<url>``  Added: 2022/07/23

    ``SendToHTTP,http://<host>:<Portnumber>/<url>``  Added: 2022/07/23
    
    ``SendToHTTP,http://<user>:<pass>@<host>:<Portnumber>/<url>``  Added: 2022/07/23

    Example:

    ``sendtohttp,192.168.10.114,80,'control?cmd=event,poff'``
    
    On completion of the command, the returned status code can be handled in a generated event, f.e. ``http#hostname=404`` for not found error, or ``http#hostname=200`` for success.
    "
    "
    SendToUDP","
    :green:`Rules`","
    Send command to other network device using UDP (non-ESP Easy units)

    ``SendToUDP,<IP address>,<Portnumber>,<command>``"
    "
    Settings","
    :red:`Internal`","
    Show settings on serial terminal

    ``Settings``"
    "
    Subnet","
    :red:`Internal`","
    Get or set the network subnet setting

    ``Subnet``

    Example output: ``Subnet:255.255.255.0(DHCP)``

    ``Subnet,255.255.255.0``"
    "
    Subscribe","
    :green:`Rules`","
    Subscribes to a specific topic using MQTT broker service

    ``Subscribe,<topic>``"
    "
    TaskClear","
    :red:`Internal`","
    Delete the given task/device

    ``TaskClear,<task nr/task name>``"
    "
    TaskClearAll","
    :red:`Internal`","
    Delete ALL task/device

    ``TaskClearAll``"
    "
    TaskDisable","
    :red:`Internal`","
    Disable a task.
    This will not save the settings, but if the settings get saved anyway the task will remain disabled at reboot.

    ``TaskDisable,<task nr/task name>``"
    "
    TaskEnable","
    :red:`Internal`","
    Enable a task. (only possible when a plugin is assigned to the task)
    This will not save the settings, but if the settings get saved anyway the task will remain enabled at reboot.

    ``TaskEnable,<task nr/task name>``"
    "
    TaskRun","
    :red:`Internal`","
    Run/excecute the given task/device, use to manually force an update/read of the task.

    ``TaskRun,<task nr/task name>``"
    "
    TaskValueSet","
    :green:`Rules`","
    Set values on a **Dummy Task** (device).

    ``TaskValueSet,<task nr/task name>,<value nr/value name>,<value/formula>``"
    "
    TaskValueSetAndRun","
    :green:`Rules`","
    Set values on a **Dummy Task** (device) and run/execute the task/device, to manually force an update/read of the task.

    ``TaskValueSetAndRun,<task nr/task name>,<value nr/value name>,<value/formula>``"
    "
    TimerPause","
    :green:`Rules`","
    Pause a timer

    ``TimerPause,<timer number>``"
    "
    TimerResume","
    :green:`Rules`","
    Resume a paused timer

    ``TimerResume,<timer number>``"
    "
    TimerSet

    TimerSet_ms","
    :green:`Rules`","
    Start a timed event

    * ``TimerSet,<timernr>,<timeInSeconds>``
    * ``TimerSet_ms,<timernr>,<time in msec>``
    * ``TimerSet,<timernr>,0`` (disables the timer)

    See also ``LoopTimerSet``

    N.B. the timernr is shared between ``TimerSet`` and ``LoopTimerSet``"
    "
    TimeZone","
    :red:`Internal`","
    Get or set the TimeZone

    ``TimeZone``

    Example output: ``TimeZone:60``

    ``TimeZone,<minutes from UTC>``"
    "
    UdpPort","
    :red:`Internal`","
    Set the udp port

    ``UdpPort,<port>``"
    "
    UdpTest","
    :red:`Internal`","
    Send a test message to an udp port, for <count> number of times

    ``UdpTest,<port>,<count>``"
    "
    Unit","
    :red:`Internal`","
    Set the unit number

    ``Unit,<unit number>``"
    "
    UseNTP","
    :red:`Internal`","
    Get or set the status of NTP (Network Time Protocol)

    ``UseNTP``

    Example output: ``UseNTP:true``

    ``UseNTP,<0/1>``"
    "
    WdConfig","
    :red:`Internal`","
    Configure external Watchdog device

    ``WdConfig,<address>,<command>,<data>``"
    "
    WdRead","
    :red:`Internal`","
    Read from external Watchdog device

    ``WdRead,<address>,<pointer/register>``"
    "
    WifiAPKey","
    :red:`Internal`","
    Change AP WPA key

    ``WifiAPKey,<WPA key>``"
    "
    WifiAllowAP","
    :red:`Internal`","
    Uncheck the setting to prevent starting AP when unable to connect to a network.

    ``WifiAllowAP``"
    "
    WifiAPMode","
    :red:`Internal`","
    Force the unit into AP mode.

    ``WifiAPMode``"
    "
    WifiConnect","
    :red:`Internal`","
    Connect to configured wireless network

    ``WifiConnect``"
    "
    WifiDisconnect","
    :red:`Internal`","
    Disconnect from wireless network

    ``WifiDisconnect``"
    "
    WifiKey","
    :red:`Internal`","
    Change WPA key for primary WiFi

    ``WifiKey,<Wifi WPA key>``"
    "
    WifiKey2","
    :red:`Internal`","
    Change WPA key for secondary WiFi

    ``WifiKey2,<Wifi WPA key>``"
    "
    WifiScan","
    :red:`Internal`","
    Scan Wireless networks

    ``WifiScan``"
    "
    WifiSSID","
    :red:`Internal`","
    Change SSID to connect as primary WiFi

    ``WifiSSID,<SSID>``"
    "
    WifiSSID2","
    :red:`Internal`","
    Change SSID to connect as secondry WiFi

    ``WifiSSID2,<SSID>``"
    "
    WifiSTAMode","
    :red:`Internal`","
    Force the unit into STA mode.

    ``WifiSTAMode``"



Event command
~~~~~~~~~~~~~

The event command is a special command used to trigger an event. This event can then be acted upon from the rules.
You can send 0..4 event values along with the event.

An event will be executed immediately if its origin demands a state update.
For events which do not need to be executed immediately, we have the AsyncEvent, which is added to an event queue.
This queue is processed 10 times per second, one event at a time.

Try to use AsyncEvents where possible, to keep rules processing times low.


.. csv-table::
    :header: "Event / Info"
    :widths: 1

    "
    ``Event,SingleEvent``

    The event (triggered by any of the launch ways) will make the unit publish a message.

    **Rules example**

    .. code-block:: none

        on SingleEvent do
          Publish,%sysname%/Info,A single event has been triggered!
        endon
    "
    "
    ``Event,SingleValue=123``

    The event value ``123`` is intercepted and published.

    **Rules example**

    .. code-block:: none

      on SingleValue do
        Publish,%sysname%/Info,An event has been sent (%eventvalue%)!
      endon
    "
    "
    ``Event,Multi=1,2,3,99``

    The event value ``99`` (4) is intercepted and the rule ``TaskValueSet...`` is
    triggered, value of task 12 value 1 is then ``1 + 2`` = ``3`` or ``1 - 2`` = ``-1``.

    **Rules example**

    .. code-block:: none

      on Multi do
        if %eventvalue4%=99
          TaskValueSet,12,1,[%eventvalue1%+%eventvalue2%]
        else
          TaskValueSet,12,1,[%eventvalue3%-%eventvalue2%]
        endif
      endon
    "