Communication - Serial Server¶

Plugin details¶

Type: Communication

Name: Serial Server

Status ESP32: NORMAL

Status ESP8266: NORMAL

GitHub: P020_Ser2Net.ino

Maintainer: .

Used libraries: .

Supported hardware¶

Configuration¶

Name In the Name field a unique name should be entered.
Enabled When unchecked the plugin is not enabled.

Sensor¶

See: Serial Helper configuration

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:

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:

../_images/P020_EventProcessingOptions.png

None: No special processing, what is received is sent out to the network client, not generating an event.
Generic: No special processing, received data is sent to the network client, and an event !Serial#<message>, containing the message as is, is generated. Spaces and newlines are processed as configured below.
RFLink: Specifically designed for receiving serial data from RFLink devices, it follows this process:
- Remove the regular RFLink 20;xx; prefix
- Check for prefix ESPEASY;, if found, remove the prefix and generate event RFLink#<message>. The <message> will contain commands to be handled by ESPEasy.
- If previous prefix is not found, generate event !RFLink#<message>, containing the entire received data. Spaces and newlines are processed as configured below.
  
  Also see the Multiple lines processing option, below.
P1 WiFi Gateway: Process the data, received from a P1 Energy meter, that does a checksum validation, as included in the message. No separate data values are available in ESPEasy, these are usually handled by Home automation systems that support the P1 protocol via TCP network communication. An event <TaskName>#Data is generated when a valid P1 packet is received.

Replacing spaces or newlines should be disabled for the P1 protocol data to be handled properly as these replacements will disturb the checksum calculation, and also, the Multiple lines processing should be disabled if the data is to be handled as P1 protocol data, as that does contain newlines.

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:

Use Serial Port as eventname: Instead of the default !Serial#<data> event, the name of the configured serial port will be used: (Only available for Generic Event processing)

(Unchecked) -> Serial
HW Serial0 -> serial0
HW Serial0 swap -> serial0swap
HW Serial1 -> serial1
HW Serial2 -> serial2
SW Serial -> serialsw
I2C Serial -> seriali2c
USB HWCDC -> serialhwcdc
USB CDC -> serialcdc

Append Task Number to eventname: Will append the task number to the event name, f.e. Serial8 or RFLink12 when task 8 or 12 is in use for this plugin. Can be combined with Use Serial Port as eventname if that is option is shown, resulting f.e. in serial0swap6 etc. (Only available for Generic and RFLink Event processing)

Replace spaces in event by: Here a single character can be selected to replace all spaces during receiving the data.
Replace newlines in event by: Here a single character can be selected to replace all newlines during receiving the data. When enabled, all linefeeds are replaced, and all carriage returns (if any) are discarded.

../_images/P020_ReplaceCharInEventOptions.png

The available set of replacement characters is , ; : . ! ^ | / \ (comma, semicolon, colon, period, exclamation, caret, pipe, slash and backslash). When set to None, no replacement will be done.

Process events without client: By default, if no network client is connected, no serial data will be received and processed either. Enabling this option enables receiving data and generating events without a TCP client connected.
Multiple lines processing: When enabled, all received data will be split at a linefeed and sent out/event generated as separate messages.
RX Receive timeout (mSec): If parts of serial data packets are somewhat delayed, but should still be handled as a single message, then the delay to wait for the next part can be configured here. 0 disables the delay.
Reset target after init: Select a GPIO pin that should be pulled low once during initialization of the plugin, used to synchronize the external serial data source with the plugin.
RX Buffer size (bytes): To not overburden the memory use of the plugin, the buffer size is set rather low. Some serial devices, like energy meters may require a larger buffer if the message exceeds this size. Range: 256..1024.

Led¶

Led enabled: To enable a data is being processed activity led.
Led pin: The GPIO pin the Led is connected to.
Led inverted: Iverts the on/off state for the Led.

Data Acquisition¶

This group of settings are standard available configuration items.

Single event with all values: When this setting is enabled, all available values will be sent in a single event <TaskName>#All, with all values in order as arguments to the event.
Show derived values: When checked, the Devices overview page, and the /json endpoint (used for updating the Devices overview page) will include any Derived values as defined. See the TaskValueSetDerived and TaskValueSetPresentation commands.
Event & Log derived values: When checked, the Derived values will be generated as Events, to be handled in Rules, and sent to logging devices like the Syslog server and/or SD-card logging.

(The derived values options are only available if String variables feature is included in the build.)

Send to Controller: Select the Controller(s) to send the Values to, either on a TaskRun command applied to the task, or on an Interval time action.

Send to Controller is only visible when one or more Controllers are configured.

Depending on the controller capabilities, some configuration settings may be shown:

../_images/Task_config_page_Controllers_section.png

All configured Controllers are shown here, including the enabled or disabled state (multiple Controllers can be enabled, only a single MQTT Controller can be enabled at one time!).

For each controller the user can select wether the data should be sent on each Interval (or explicit TaskRun).

For the Domoticz controllers the value index (IDX) has to be configured.

For some controllers, like Home Assistant/openHAB, there are extra options available.

Group: This represents the group id to combine all values from multiple tasks into a single grouped-device during MQTT AutoDiscovery. Groups, by design, can span multiple ESPEasy devices, if desired, as long as the Task/Valuename combinations are unique. If a group should only combine Tasks from a single ESPEasy unit, the group id should be unique across multiple ESPEasy units. The group description, default Group <n>, can be adjusted in Home Assistant. If the Group value matches the current Unit nr, the Unit name, %sysname%, is used instead of Group <nr>.
Retained: For MQTT Controllers, this setting can be enabled to send the values for the current task with the Retain flag set. The Publish Retain flag in the Controller settings will override this by sending all task values with Retain flag enabled.
Send derived: This checkbox determines if any configured Derived values should also be sent to the controller (and included in the AutoDiscovery if that’s available and enabled).
Resend MQTT Discovery: When checked, will start a resend of the MQTT Discovery process for this task after a random delay, when Submit is clicked, so any changed settings will be updated in the MQTT broker. This setting is only available if the controller is enabled, the Auto Discovery feature is available and enabled for the controller. This setting is not stored.

Other controllers, like f.e. FHEM HTTP, do not support additional settings besides the checkbox to enable sending the data.

Commands¶

Command	Extra information
`serialsend,<content to send>` `<content to send>`: Text that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the serial port.	Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.
`ser2netclientsend,<content to send>` `<content to send>`: Text that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the network client.	This command will only send data to the network client, when there is an active connection. Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the network client. No extra data is added, other than any (system) variables that are included, being replaced.
`serialsendmix,'<content to send>'[,...]` `<content to send>`: Text and/or hex byte(s) (having 0x prefix) that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the serial port.	This command requires quotes to be used if spaces or commas are part of the content. Any data can be sent, even if it can not be typed in a text content, by specifying that as a separate argument: `serialsendmix,'text, optionally including spaces or commas',0xXX,'0xXXxx XX,xx-XX:xx'` `'text, optionally including spaces or commas'`: Any text content to be sent to the serial port. Can contain variables. Quotes are only required if spaces or commas (separators) are used. `0xXX`: A single character in hexadecimal notation (range: 0x00..0xFF), that is appended to the data to send. `'0xXXxx XX,xx-XX:xx'`: A sequence of hexadecimal values (range: 0x00..0xFF), that can be separated by a space, comma, dash, colon, semicolon or period, or are just entered adjecent. Only the first 2 characters should be `0x` or `0X`, the rest is interpreted as hex bytes, and appended to the string to send. Quotes are only required if space or comma separators are used. Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.
`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.

Command

Extra information

serialsend,<content to send>

<content to send>: Text that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the serial port.

Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.

ser2netclientsend,<content to send>

<content to send>: Text that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the network client.

This command will only send data to the network client, when there is an active connection.

Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the network client. No extra data is added, other than any (system) variables that are included, being replaced.

serialsendmix,'<content to send>'[,...]

<content to send>: Text and/or hex byte(s) (having 0x prefix) that will be sent (nearly) unprocessed. Only the regular variable replacements will be applied before sending the content to the serial port.

This command requires quotes to be used if spaces or commas are part of the content.

Any data can be sent, even if it can not be typed in a text content, by specifying that as a separate argument: serialsendmix,'text, optionally including spaces or commas',0xXX,'0xXXxx XX,xx-XX:xx'

'text, optionally including spaces or commas': Any text content to be sent to the serial port. Can contain variables. Quotes are only required if spaces or commas (separators) are used.

0xXX: A single character in hexadecimal notation (range: 0x00..0xFF), that is appended to the data to send.

'0xXXxx XX,xx-XX:xx': A sequence of hexadecimal values (range: 0x00..0xFF), that can be separated by a space, comma, dash, colon, semicolon or period, or are just entered adjecent. Only the first 2 characters should be 0x or 0X, the rest is interpreted as hex bytes, and appended to the string to send. Quotes are only required if space or comma separators are used. Using this command, either from rules, via http or mqtt, the text that is provided as content is completely sent to the serial port. No extra data is added, other than any (system) variables that are included, being replaced.

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.

Change log¶

Changed in version 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 Major overhaul for 2.0 release.

Added in version 1.0: …

added Initial release version.