Modules/Serial - OpenSCADAWiki

# Modules/Serial

English • ‎mRussian • ‎Українська

Module | Name | Version | License | Source | Languages | Platforms | Type | Author | Description
--- | --- | --- | --- | --- | --- | --- | --- | --- | ---
Serial | Serial interfaces | 2.7 | GPL2 | tr_Serial.so | en,uk,ru,de,pt | x86,x86_64,ARM | Transport | Roman Savochenko Maxim Kochetkov (2016), Maxim Lysenko (2009-2010) — the page initial translation | Provides transport based on the serial interfaces. It is used for data exchanging via the serial interfaces of the type RS232, RS485, GSM and similar. To Do: - test the modem mode and append to it for the PIN entering field.

The module provides support for transports based on serial interfaces such as RS232, RS485, GSM and similar. Input and output transports is supported. You can add new input and output interfaces through the configuration of the transport subsystem in any OpenSCADA configurator.

The module, in the modem mode, supports a mixed mode of operation, which involves the presence of an input transport, which expects external connections, as well as an output transport on the same device. That is, the input transport will ignore all requests in the presence of the output transport connection, while the output transport will not attempt to establish a connection in the presence of the connection to the input transport or the connection of another output transport, for example, another telephone number.

In the normal mode of the serial interface, multiple use of one and the same port in input and output transports is not allowed. A global blocking of the serial device is not performed due to the ambiguity of this process at the system level, and multiple use can lead to unpredictable and difficult-to-understand issues. If you need to organize a local serial channel with a couple of linked ports, it is recommended to use the command socat -d -d pty,raw,echo=0,perm=0666 pty,raw,echo=0,perm=0666.

## 1 Input transports

The configured and running input transport opens a serial port to wait for user requests. Each input interface is necessarily associated with one of the available transport protocols to which incoming messages are transmitted.

Fig.1. The generic configuration dialogues of the input serial interface.

Using the main dialog you can set:

- State of transport, that is: status, "Connect" and name of the database, containing the configuration.
- Identifier, name and description of the transport.
- Address of the transport in the format "{dev}[:{spd}[:{format}[:{opts}[:{mdm}]]]]", where:
  - dev — address of the serial device (/dev/ttyS0);
  - spd — speed of the serial devices from a number: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 500000, 576000 or 921600;
  - format — asynchronous data format "{size}{parity}{stop}" (8N1, 7E1, 5O2, ...);
  - opts — different options, mostly for flow control, separated by ',':
    - "[-]h" — hardware (CRTSCTS);
    - "[-]s" — software (IXON|IXOFF);
    - "rts" — using of the RTS signal for transferring(false) and checking for echo, for raw RS-485;
    - "rts1" — using of the RTS signal for transferring(true) and checking for echo, for raw RS-485;
    - "rtsne" — using of the RTS signal for transferring(false) and without checking for echo, for raw RS-485;
    - "rts1ne" — using of the RTS signal for transferring(true) and without checking for echo, for raw RS-485;
    - "[-]RS485" — using RS-485 mode, through TIOCSRS485.
  - mdm — modem mode, listen for "RING".
- Choice of transport protocols.
- The state "Connect", in which the transport must be translated at boot.

Using the additional dialog you can set:

- Time intervals of the interface in the format of string "{symbol}:{frm}[::{rtsDelay1}:{rtsDelay2}]", where:
  - symbol — character time in milliseconds, used to control of the frame end;
  - frm — maximum time of the frame in milliseconds, used to limit the package maximum size of the request — the frame;
  - rtsDelay1 — delay between the transmitter activation with RTS signal and start up of the transmission, in milliseconds;
  - rtsDelay2 — delay between the transmitting and disconnecting the transmitter with RTS signal, in milliseconds.
- Priority of the input stream task.
- [MODEM] Modem parameters. This mode is activated by the fifth parameter of the address and includes call waiting from the remote modem (the request "RING"), answering the call (the command "ATA") and the subsequent transfer of requests from the remote station to the transport protocol. The disconnection of the communication session is performed by the connection initiator and leads to the reconnection of the receiver modem to wait for new calls.
  - Requests timeout of the modem, in seconds.
  - Time delay before initializing the modem, in seconds.
  - Time delay after initializing the modem, in seconds.
  - First initialization string (typically contains the reset command of the modem "ATZ").
  - Second initialization string.
  - Result string of the modem's initialization (usually "OK"), with which the modem answers for initializing and which must be expected.
  - Call's request (usually "RING"), which is sent by the modem in the case of an output call.
  - Answer to the call (usually "ATA"), which is sent to the modem to answer the call.
  - Result line for the answer to the call (usually "CONNECT"), with which the modem answers to the answer command, and that is to be expected.
- Protocols' specific custom parameters.
- Reset all the additional parameters to default values and cleanup the protocols' specific custom parameters.

## 2 Output transports

Configured and running output transport opens port of the serial interface to send the requests through it.

Fig.2. The generic configuration dialogues of the output serial interface.

Using the main dialog you can set:

- The state of transport, that is: status, "Connect" and name of the database, containing the configuration.
- Identifier, name and description of the transport.
- Address of the transport in the format "{dev}[:{spd}[:{format}[:{opts}[:{modTel}]]]]", where:
  - dev — address of the serial device (/dev/ttyS0);
  - spd — speed of the serial devices from a number: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 500000, 576000 or 921600;
  - format — asynchronous data format "{size}{parity}{stop}" (8N1, 7E1, 5O2, ...);
  - opts — different options, mostly for flow control, separated by ',':
    - "[-]h" — hardware (CRTSCTS);
    - "[-]s" — software (IXON|IXOFF);
    - "rts" — using of the RTS signal for transferring(false) and checking for echo, for raw RS-485;
    - "rts1" — using of the RTS signal for transferring(true) and checking for echo, for raw RS-485;
    - "rtsne" — using of the RTS signal for transferring(false) and without checking for echo, for raw RS-485;
    - "rts1ne" — using of the RTS signal for transferring(true) and without checking for echo, for raw RS-485;
    - "[-]RS485" — using RS-485 mode, through TIOCSRS485.
  - modTel — modem phone, presence of this field switches transport to work in the modem mode.

Using the additional dialog you can set:

- Time intervals of the interface in format of the string "{conn}:{symbol}[-{NextReqMult}][:{KeepAliveTm}[:{rtsDelay1}:{rtsDelay2}]]", where:
  - conn — maximum time of waiting the connecting response, in milliseconds;
  - symbol — maximum time of one symbol, used for the frame end detection, in milliseconds;
  - NextReqMult — next request's multiplicator to the symbol time, 4 by default;
  - KeepAliveTm — keep alive timeout to restart the transport, in seconds; use the value < 0 for stopping the transport after missing response at each request;
  - rtsDelay1 — delay between the transmitter activation with RTS signal and start up of the transmission, in milliseconds;
  - rtsDelay2 — delay between the transmitting and disconnecting the transmitter with RTS signal, in milliseconds.

  Can be prioritatile specified into the address field as the second global argument, as such "/dev/rfcomm0:9600||1000:40-20".

- Do not disconnect at processing. Sometimes the closing of an open device can be destructive, for example, on an ICP-DAS LP PLC, and you can prevent it with this option.
- [MODEM] Modem parameters. This mode is enabled by the fifth parameter presence of the address and it involves making a call on the phone specified by this parameter at the start time of the transport. After establishing a connection to the remote modem, all transmission requests are sent to the remote modem station. Disconnection of a communication session, with the transport stopping, is carried out according to the activity timeout.
  - Requests timeout of the modem, in seconds.
  - Lifetime of the connection, in seconds. If during this time there will be no data transmission over the transport the connection will be aborted.
  - Delay time before initializing the modem, in seconds.
  - Delay time after initializing the modem, in seconds.
  - First initialization string (typically contains the reset command "ATZ" of the modem).
  - Second initialization string.
  - Result string of the modem's initialization (usually "OK"), with which the modem answers for initializing and which must be expected.
  - Dialling string to the remote modem (usually "ATDT"). When dialing, the phone number is added to this prefix.
  - Result string of the successful connection (usually "CONNECT").
  - Result string of the busy line (usually is "BUSY").
  - Result string of the absence of the carrier in line (usually "NO CARRIER").
  - Result string of the dial tone lack in the line (usually "NO DIALTONE").
  - Exit string from the data mode (usually "+++") and the "Delay time before initializing the modem" is used, after it.
  - Hang up command (usually "+++ATH"). This command is called whenever there is need to break the connection.
  - Result string of the hanging up command (usually "OK"), with which the modem answers to the command and which must be expected.
- Protocols' specific custom parameters.
- Reset all the additional parameters to default values and cleanup the protocols' specific custom parameters.

The transport can work with the I2C hardware bus, if "/dev/i2c-{N}" is selected as the device and the bus will allow to set the slave device address by the I2C_SLAVE command from the first request byte. Speed and format do not play a role in this mode. From the timeouts here actually only the symbol time works and mainly for calculating the expectation of the request repetition.

## 3 User programming API

Object "Output transport" (SYS.Transport.Serial.out_{OutTransport})

- bool TS( bool rts = EVAL ) — controls the sending, setting the request rts, and returns the Clear CTS state.
- bool DR( bool dtr = EVAL ) — controls the readiness of the device, through setting of the terminal readiness dtr, and returns the state of readiness DSR.
- bool DCD() — state of the Data Carrier Detect.
- bool RI() — Ring Indicator.
- int sendbreak( int duration = 0 ) — sends to the stream the interruptions with zeros for duration (0 is some default duration).

## 4 Notes

Communications via the serial interfaces have a number of features. The most important feature is the criterion for the end of the message and the waiting time of this criterion. In some protocols, such a criterion is a sign of the end or the specified message size. In other protocols, such a criterion is no data in the input stream for a specified time — the symbol time. In both cases, the criterion waiting time, or the symbol, is a crucial and strongly affects the overall exchange time and the data integrity. Consequently, the smaller this time, the better if you have no loss the data tail. Here the problem of hardware and its drivers latency happens.

To check for latency of the exchange channel, thus optimally adjust the symbol time, you can use the interface of the "Request" tab of the output transport. To do this, you need to specify an exemplary request for the protocol, specify "Wait timeout", send a request, and check its integrity. To get a more representative result, you need to repeat the request several times. If there is an incomplete response, then the time of the symbol must be increased, otherwise you can reduce it.

On embedded serial interfaces RS232/422/485 hardware you can achieve low latency — up to several milliseconds. However, on high-loaded systems with many tasks in the real-time priority, latency may become non-deterministic, due to the execution of the service thread of the Linux kernel events in low priority. To solve this problem, you must set a high priority to these threads, which can be done using a script, placing it, for example, in "/etc/rc.local":

    #!/bin/sh

    # Setting the high priority for events kernel threads to rise the serial interfaces reaction
    events=`ps -Ao pid,comm | sed -n '/[ ]*\([^ ]\)[ ]*events\/[0-9]/s//\1/p'`
    for ie in $events; do
      chrt -pr 21 $ie
    done

This script does not make sense for real-time Linux cores, with the PREEMPT_RT patch, since all interrupt and message threads are already running there in real-time priority.

On the external serial interfaces hardware, such as adapters USB->RS232/422/485, you may meet the problems of high latency associated with the feature of hardware implementation or its driver. To solve this problem you need study the configuration of the equipment or adjust the large waiting time — symbol time!

In the like way you can determine an optimal connection time, that is: set the connection time to the default value for this speed (sets when changing the speed in the address), remove the "Wait timeout", send a request. If the answer is come then we take the measured response time of the device, double and set the value as the connection time. An unreasonable excess of the connection time will lead to high expectations in the absence of the device, as well as to trigger the protective timeouts of the internal procedures!

On the market there are USB->Serial converters that work only with terminals, that is, they can transmit and process only ASCII characters and can not be switched to binary mode. Known instances of such converters: PL2303TA (Y-105).

### 4.1 Virtual/local serial interfaces

Often for local checking, without physical hardware, you may need the ports pair connected each other. For the ports creation and more other operations on serial stream you can use utility socat. For example, to create two linked ports you need call a command which will create and print their addresses:

    socat -d -d pty,raw,echo=0,perm=0666 pty,raw,echo=0,perm=0666
    #2013/07/02 16:37:29 socat[10402] N PTY is /dev/pts/6
    #2013/07/02 16:37:30 socat[10402] N PTY is /dev/pts/7
    #2013/07/02 16:37:30 socat[10402] N starting data transfer loop with FDs [3,3] and [5,5]

### 4.2 Serial interfaces transferring through Ethernet network

In some cases, it is useful to transfer the serial interface port of the remote machine to the local port, for example, to poll the devices connected to the serial interface of the remote machine. Of course, if you install OpenSCADA on the remote machine in the PLC configuration, then you can immediately process the data, pre-buffering/archiving, and so on, but sometimes the hardware can be complicated to launch OpenSCADA, where saves the ability to throw over the serial stream over the network. To solve this problem you can use the same utility socat or remserial, ser2net, which can be built and run on the remote machine. Examples of throwing over the serial port:

    # Creating a socket on port 5555 on the remote computer, for the serial port /dev/ttyS0
    socat tcp-l:5555,reuseaddr,fork file:/dev/ttyS0,raw
    # Connecting to the socket of the reflected port of the remote machine and creating a file of the mirrored local interface.
    socat -d -d pty,raw,echo=0,perm=0666 tcp:192.168.2.4:5555,mss=1400
    #2013/07/04 10:09:09 socat[12947] N PTY is /dev/pts/4
    #2013/07/04 10:09:09 socat[12947] N opening connection to AF=2 192.168.2.4:5555
    #2013/07/04 10:09:09 socat[12947] N successfully connected from local address AF=2 192.168.2.61:33493
    #2013/07/04 10:09:09 socat[12947] N starting data transfer loop with FDs [3,3] and [5,5]

In the case of "socat", and possibly other utilities, you can omit the EthernetTCP->Serial driver starting on the client side and connect OpenSCADA directly to the TCP port of the remote device.

In operation via the EthernetTCP->Serial driver there is a feature that is associated with the presence of two connection timeouts: one in the driver and one in Transport.Sockets. It is important that the value of this timeout in Transport.Sockets is greater than in the driver, otherwise it is possible to shift and receive delayed replies from previous queries.

More manufacturers of industrial communication hardware produce ready converters from Ethernet to RS-232/422/485, which you can use with OpenSCADA in similar way. Here are comments and a list of the converters for what OpenSCADA working tested:

- ICP DAS: tDS-7xx — configures by WEB-interface and works straight on connection to TCP-port;
- Tibbo: DS100 — configures only by a program for MS Windows®, provides self driver for virtual serial interfaces preparing on Linux, works straight on connection to TCP-port.

Modules/Serial/en - GFDL | May 2026 | OpenSCADA 0.9.9