Merge pull request #5287 from tonhuisman/feature/P020-data-handling-improvements

[P020] Improve data handling, add UDP receiver

docs/source/Plugin/P020.rst

@@ -45,6 +45,18 @@ Device Settings
 
 * **TCP Port**: The port for an external network client to read the data from, range 1..65535. The used port number must be unique within the device.
 
+* **Protocol**: Select the protocol(s) to listen for on the selected port. Available options:
+
+.. image:: P020_ProtocolOptions.png
+
+* *TCP (Default)*: The original plugin only listened for TCP connections, so that's the default setting.
+
+* *UDP*: Listen for incoming data using the UDP protocol.
+
+* *TCP & UDP*: Listen using TCP for an active connection, and also listen using UDP for incoming data.
+
+As UDP uses a stateless connection, and is only used for *receiving* data, this is not recognized as an external device listening. Data received via UDP is sent to the serial port verbatim, so a serial port must be configured. TCP and UDP can use a matching connection on the same port number, at the same time.
+
 * **Baud Rate / Serial config**: See *Serial helper configuration*, above.
 
 * **Event Processing**: Select the type of data that is expected, to enable correct preprocessing. Available options:
@@ -71,6 +83,9 @@ Device Settings
 
 * **P1 #data event with message**: When enabled, the *P1 WiFi Gateway* Event Processing option will include the received message. **WARNING** This may easily cause memory overflow exceptions, especially when running on ESP8266 or other low-memory situations!
 
+* **Event data hex format**: When enabled, the data received will be emitted in hex format (starts with ``0x`` and all bytes hex encoded), instead of the regular text format. This enables for received binary data to be passed to an external receiver without losing special bytes like ``0x00`` etc.
+
+
 When selecting the **Event processing** options *Generic* or *RFLink*, after submitting the page will show extra options for the events generated:
 
 .. image:: P020_EventOptions.png
@@ -138,6 +153,8 @@ Change log
 .. versionchanged:: 2.0
   ...
 
+  |changed| 2025-03-30: Add Protocol (for receiving data via UDP) and Event data hex format options.
+
   |changed| 2022-12-13: Merge of P020 and P044 to reduce code size and combine features, as P044 was initially started as a spin-off from P020, but not evolved with the P020 features.
 
   |added|

docs/source/Plugin/P020_commands.repl

@@ -35,3 +35,10 @@
         ``'0xXXxx XX,xx-XX:xx'``: A sequence of hexadecimal values (range: 0x00..0xFF), that *can* be separated by a space, comma, dash, colon, semicolon or period, or are just entered adjecent. Only the first 2 characters should be ``0x`` or ``0X``, the rest is interpreted as hex bytes, and appended to the string to send. Quotes are only required if space or comma separators are used.
         Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.
         "
+        "
+        ``serialsend_test,'<content to place in serial buffer>'``
+
+        ``<content to place in serial buffer>``: Text that will be put into the serial buffer (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the serial port.
+        ","
+        This command is intended for testing as if data was received via serial. After placing the data in the buffer, the regular handling of that data is initiated.
+        "

docs/source/Rules/Rules.rst

@@ -493,7 +493,7 @@ the '=' sign).
 For historic reasons, ``%eventvalue%`` without a number, can also be used to access the first event value.
 Thus it will be the same when using ``%eventvalue1%``.
 
-There is one exception; When the event starts with an ``!``,  ``%eventvalue%`` does refer to the literal event, or the part of the event after the ``#`` character.
+There is one exception; When the event starts with an ``!``,  ``%eventvalue%`` does refer to the literal event, an with ``%eventname%`` and ``%eventpar%`` the part left and right of the ``#`` character can be used (processing ``%eventname%`` and ``%eventpar%`` was added 2025-03-30).
 This was introduced for the Serial Server plugin (P020) which sends events like ``!Serial#`` followed by the received string.
 
 
@@ -931,6 +931,10 @@ Usage: ``{substring:<startpos>:<endpos>:<string>}``
 
 The position arguments are the same as in Arduino ``String::substring`` , meaning the endpos is 1 position further than the last character you need.
 
+Added: 2025-03-31
+
+If ``<endpos>`` is not provided or invalid (the colon has to stay included!), the remainder of ``<string>`` beginning at ``<startpos>`` is returned (like Arduino behavior).
+
 For example:
 
 .. code-block:: none