<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
<html class="client-nojs" dir="ltr" lang="en">
<head>
<meta charset="UTF-8" />
<title>Modules/Serial - OpenSCADAWiki</title>
<meta content="MediaWiki 1.26.4" name="generator" />
<link href="https://www.gnu.org/copyleft/fdl.html" rel="copyright" />
<link href="../files/doc.css" rel="stylesheet" /></head>
<body><div class="floatright"><a href="../index.html"><img alt="OpenSCADA" src="../../en/files/index.png" /></a></div><div id="mw_header">
<div class="mw-indicators">
</div>
<h1 id="firstHeading" lang="en">Modules/Serial</h1>
</div><div class="mw-content-ltr" dir="ltr" id="mw-content-text" lang="en"><div class="mw-pt-languages" dir="ltr" lang="en"><div class="mw-pt-languages-list autonym"><span class="mw-pt-languages-ui mw-pt-languages-selected mw-pt-progress mw-pt-progress--complete">English</span> • ‎<a class="mw-pt-progress mw-pt-progress--high" href="../../ru/Modules/Serial.html" title="Модули/Serial (75% translated)">mRussian</a> • ‎<a class="mw-pt-progress mw-pt-progress--complete" href="../../uk/Modules/Serial.html" title="Модулі/Serial (100% translated)">УкраїнÑька</a></div></div>
<table class="wikitable">
<tr>
<th> Module </th>
<th> Name </th>
<th> Version </th>
<th> License </th>
<th> Source </th>
<th> Languages </th>
<th> Platforms </th>
<th> Type </th>
<th> Author </th>
<th> Description
</th></tr>
<tr>
<td> <a href="../Modules/Serial.html" title="Special:MyLanguage/Modules/Serial">Serial</a> </td>
<td> Serial interfaces
</td>
<td> 2.7 </td>
<td> GPL2 </td>
<td> tr_Serial.so </td>
<td> en,uk,ru,de </td>
<td> x86,x86_64,ARM
</td>
<td> Transport </td>
<td> Roman Savochenko<br /> <font size="-2"><i>Maxim Kochetkov (2016), Maxim Lysenko (2009-2010) — the page initial translation</i></font> </td>
<td> 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.
<ul><li> <b><a href="../To_do.html" title="Special:MyLanguage/Works/To do">To Do</a>:</b></li></ul>
<dl><dd> - test the modem mode and append to it for the PIN entering field.</dd></dl>
</td></tr></table>
<p>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.
</p><p>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.
</p><p><a class="image" href="http://oscada.org/wiki/File:At.png"><img alt="At.png" height="22" src="../files/At.png" width="22" /></a> 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 <span style="border: solid gray 1px; padding: 1px; font-family: monospace; font-size: 1.2em; white-space: nowrap;">socat -d -d pty,raw,echo=0,perm=0666 pty,raw,echo=0,perm=0666</span>.
</p>
<div class="toc" id="toc"><div id="toctitle"><h2>Contents</h2></div>
<ul>
<li class="toclevel-1 tocsection-1"><a href="#Input_transports"><span class="tocnumber">1</span> <span class="toctext">Input transports</span></a></li>
<li class="toclevel-1 tocsection-2"><a href="#Output_transports"><span class="tocnumber">2</span> <span class="toctext">Output transports</span></a></li>
<li class="toclevel-1 tocsection-3"><a href="#User_programming_API"><span class="tocnumber">3</span> <span class="toctext">User programming API</span></a></li>
<li class="toclevel-1 tocsection-4"><a href="#Notes"><span class="tocnumber">4</span> <span class="toctext"><span>Notes</span></span></a>
<ul>
<li class="toclevel-2 tocsection-5"><a href="#Virtual.2Flocal_serial_interfaces"><span class="tocnumber">4.1</span> <span class="toctext">Virtual/local serial interfaces</span></a></li>
<li class="toclevel-2 tocsection-6"><a href="#Serial_interfaces_transferring_through_Ethernet_network"><span class="tocnumber">4.2</span> <span class="toctext">Serial interfaces transferring through Ethernet network</span></a></li>
</ul>
</li>
</ul>
</div>
<h2><span class="mw-headline" id="Input_transports"><span class="mw-headline-number">1</span> Input transports</span></h2>
<p>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.
</p>
<div class="center"><div class="thumb tnone"><div class="thumbinner" style="width:779px;"><a class="image" href="http://oscada.org/wiki/File:Serial_in.png"><img class="thumbimage" height="1155" src="../files/Serial_in.png" width="777" /></a> <div class="thumbcaption">Fig.1. The generic configuration dialogues of the input serial interface.</div></div></div></div>
<p>Using the main dialog you can set:
</p>
<ul><li> State of transport, that is: status, "Connect" and name of the database, containing the configuration.</li>
<li> Identifier, name and description of the transport.</li>
<li> Address of the transport in the format "<b>{dev}[:{spd}[:{format}[:{opts}[:{mdm}]]]]</b>", where:
<ul><li> <i>dev</i> — address of the serial device (/dev/ttyS0);</li>
<li> <i>spd</i> — speed of the serial devices from a number: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 500000, 576000 or 921600;</li>
<li> <i>format</i> — asynchronous data format "<b>{size}{parity}{stop}</b>" (8N1, 7E1, 5O2, ...);</li>
<li> <i>opts</i> — different options, mostly for flow control, separated by ',':
<ul><li> "[-]h" — hardware (CRTSCTS);</li>
<li> "[-]s" — software (IXON|IXOFF);</li>
<li> "rts" — using of the RTS signal for transferring(false) and checking for echo, for raw RS-485;</li>
<li> "rts1" — using of the RTS signal for transferring(true) and checking for echo, for raw RS-485;</li>
<li> "rtsne" — using of the RTS signal for transferring(false) and without checking for echo, for raw RS-485;</li>
<li> "rts1ne" — using of the RTS signal for transferring(true) and without checking for echo, for raw RS-485;</li>
<li> "[-]RS485" — using RS-485 mode, through TIOCSRS485.</li></ul></li>
<li> <i>mdm</i> — modem mode, listen for "RING".</li></ul></li>
<li> Choice of transport protocols.</li>
<li> The state "Connect", in which the transport must be translated at boot. </li></ul>
<p>Using the additional dialog you can set:
</p>
<ul><li> Time intervals of the interface in the format of string "<b>{symbol}:{frm}[::{rtsDelay1}:{rtsDelay2}]</b>", where:
<ul><li> <i>symbol</i> — character time in milliseconds, used to control of the frame end;</li>
<li> <i>frm</i> — maximum time of the frame in milliseconds, used to limit the package maximum size of the request — the frame;</li>
<li> <i>rtsDelay1</i> — delay between the transmitter activation with RTS signal and start up of the transmission, in milliseconds;</li>
<li> <i>rtsDelay2</i> — delay between the transmitting and disconnecting the transmitter with RTS signal, in milliseconds.</li></ul></li>
<li> Priority of the input stream task.</li>
<li> [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.
<ul><li> Requests timeout of the modem, in seconds.</li>
<li> Time delay before initializing the modem, in seconds.</li>
<li> Time delay after initializing the modem, in seconds.</li>
<li> First initialization string (typically contains the reset command of the modem "ATZ").</li>
<li> Second initialization string.</li>
<li> Result string of the modem's initialization (usually "OK"), with which the modem answers for initializing and which must be expected.</li>
<li> Call's request (usually "RING"), which is sent by the modem in the case of an output call.</li>
<li> Answer to the call (usually "ATA"), which is sent to the modem to answer the call.</li>
<li> 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.</li></ul></li>
<li> Protocols' specific custom parameters.</li>
<li> Reset all the additional parameters to default values and cleanup the protocols' specific custom parameters.</li></ul>
<h2><span class="mw-headline" id="Output_transports"><span class="mw-headline-number">2</span> Output transports</span></h2>
<p>Configured and running output transport opens port of the serial interface to send the requests through it.
</p>
<div class="center"><div class="thumb tnone"><div class="thumbinner" style="width:823px;"><a class="image" href="http://oscada.org/wiki/File:Serial_out.png"><img class="thumbimage" height="1265" src="../files/Serial_out.png" width="821" /></a> <div class="thumbcaption">Fig.2. The generic configuration dialogues of the output serial interface.</div></div></div></div>
<p>Using the main dialog you can set:
</p>
<ul><li> The state of transport, that is: status, "Connect" and name of the database, containing the configuration.</li>
<li> Identifier, name and description of the transport.</li>
<li> Address of the transport in the format "<b>{dev}[:{spd}[:{format}[:{opts}[:{modTel}]]]]</b>", where:
<ul><li> <i>dev</i> — address of the serial device (/dev/ttyS0);</li>
<li> <i>spd</i> — speed of the serial devices from a number: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 500000, 576000 or 921600;</li>
<li> <i>format</i> — asynchronous data format "<b>{size}{parity}{stop}</b>" (8N1, 7E1, 5O2, ...);</li>
<li> <i>opts</i> — different options, mostly for flow control, separated by ',':
<ul><li> "[-]h" — hardware (CRTSCTS);</li>
<li> "[-]s" — software (IXON|IXOFF);</li>
<li> "rts" — using of the RTS signal for transferring(false) and checking for echo, for raw RS-485;</li>
<li> "rts1" — using of the RTS signal for transferring(true) and checking for echo, for raw RS-485;</li>
<li> "rtsne" — using of the RTS signal for transferring(false) and without checking for echo, for raw RS-485;</li>
<li> "rts1ne" — using of the RTS signal for transferring(true) and without checking for echo, for raw RS-485;</li>
<li> "[-]RS485" — using RS-485 mode, through TIOCSRS485.</li></ul></li>
<li> <i>modTel</i> — modem phone, presence of this field switches transport to work in the modem mode.</li></ul></li></ul>
<p>Using the additional dialog you can set:
</p>
<ul><li> Time intervals of the interface in format of the string "<b>{conn}:{symbol}[-{NextReqMult}][:{KeepAliveTm}[:{rtsDelay1}:{rtsDelay2}]]</b>", where:
<ul><li> <i>conn</i> — maximum time of waiting the connecting response, in milliseconds;</li>
<li> <i>symbol</i> — maximum time of one symbol, used for the frame end detection, in milliseconds;</li>
<li> <i>NextReqMult</i> — next request's multiplicator to the <i>symbol</i> time, 4 by default;</li>
<li> <i>KeepAliveTm</i> — keep alive timeout to restart the transport, in seconds; use the value < 0 for stopping the transport after missing response at each request;</li>
<li> <i>rtsDelay1</i> — delay between the transmitter activation with RTS signal and start up of the transmission, in milliseconds;</li>
<li> <i>rtsDelay2</i> — delay between the transmitting and disconnecting the transmitter with RTS signal, in milliseconds.</li></ul></li></ul>
<dl><dd> Can be prioritatile specified into the address field as the second global argument, as such "<b>/dev/rfcomm0:9600||1000:40-20</b>".</dd></dl>
<ul><li> 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.</li>
<li> [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.
<ul><li> Requests timeout of the modem, in seconds.</li>
<li> Lifetime of the connection, in seconds. If during this time there will be no data transmission over the transport the connection will be aborted.</li>
<li> Delay time before initializing the modem, in seconds.</li>
<li> Delay time after initializing the modem, in seconds.</li>
<li> First initialization string (typically contains the reset command "ATZ" of the modem).</li>
<li> Second initialization string.</li>
<li> Result string of the modem's initialization (usually "OK"), with which the modem answers for initializing and which must be expected.</li>
<li> Dialling string to the remote modem (usually "ATDT"). When dialing, the phone number is added to this prefix.</li>
<li> Result string of the successful connection (usually "CONNECT").</li>
<li> Result string of the busy line (usually is "BUSY").</li>
<li> Result string of the absence of the carrier in line (usually "NO CARRIER").</li>
<li> Result string of the dial tone lack in the line (usually "NO DIALTONE").</li>
<li> Exit string from the data mode (usually "+++") and the "Delay time before initializing the modem" is used, after it.</li>
<li> Hang up command (usually "+++ATH"). This command is called whenever there is need to break the connection.</li>
<li> Result string of the hanging up command (usually "OK"), with which the modem answers to the command and which must be expected.</li></ul></li>
<li> Protocols' specific custom parameters.</li>
<li> Reset all the additional parameters to default values and cleanup the protocols' specific custom parameters.</li></ul>
<p>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 <b>first request byte</b>. 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.
</p>
<h2><span class="mw-headline" id="User_programming_API"><span class="mw-headline-number">3</span> User programming API</span></h2>
<p><b>Object "Output transport" (SYS.Transport.Serial.out_{OutTransport})</b>
</p>
<ul><li> <i>bool TS( bool rts = EVAL )</i> — controls the sending, setting the request <i>rts</i>, and returns the Clear CTS state.</li>
<li> <i>bool DR( bool dtr = EVAL )</i> — controls the readiness of the device, through setting of the terminal readiness <i>dtr</i>, and returns the state of readiness DSR.</li>
<li> <i>bool DCD()</i> — state of the Data Carrier Detect.</li>
<li> <i>bool RI()</i> — Ring Indicator.</li>
<li> <i>int sendbreak( int duration = 0 )</i> — sends to the stream the interruptions with zeros for <i>duration</i> (0 is some default duration).</li></ul>
<h2><span class="mw-headline" id="Notes"><span class="mw-headline-number">4</span> <span id="Notes" title="#Notes">Notes</span></span></h2>
<p>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.
</p><p>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.
</p><p>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":
</p>
<div class="mw-highlight mw-content-ltr" dir="ltr"><pre><span class="c">#!/bin/sh</span>
<span class="c"># Setting the high priority for events kernel threads to rise the serial interfaces reaction</span>
<span class="nv">events</span><span class="o">=</span><span class="sb">`</span>ps -Ao pid,comm <span class="p">|</span> sed -n <span class="s1">'/[ ]*\([^ ]\)[ ]*events\/[0-9]/s//\1/p'</span><span class="sb">`</span>
<span class="k">for</span> ie in <span class="nv">$events</span><span class="p">;</span> <span class="k">do</span>
chrt -pr <span class="m">21</span> <span class="nv">$ie</span>
<span class="k">done</span>
</pre></div>
<p>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.
</p><p>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!
</p><p>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!
</p><p><a class="image" href="http://oscada.org/wiki/File:At.png"><img alt="At.png" height="22" src="../files/At.png" width="22" /></a> 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).
</p>
<h3><span class="mw-headline" id="Virtual.2Flocal_serial_interfaces"><span class="mw-headline-number">4.1</span> Virtual/local serial interfaces</span></h3>
<p>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 <b>socat</b>. For example, to create two linked ports you need call a command which will create and print their addresses:
</p>
<div class="mw-highlight mw-content-ltr" dir="ltr"><pre>socat -d -d pty,raw,echo<span class="o">=</span>0,perm<span class="o">=</span><span class="m">0666</span> pty,raw,echo<span class="o">=</span>0,perm<span class="o">=</span>0666
<span class="c">#2013/07/02 16:37:29 socat[10402] N PTY is /dev/pts/6</span>
<span class="c">#2013/07/02 16:37:30 socat[10402] N PTY is /dev/pts/7</span>
<span class="c">#2013/07/02 16:37:30 socat[10402] N starting data transfer loop with FDs [3,3] and [5,5]</span>
</pre></div>
<h3><span class="mw-headline" id="Serial_interfaces_transferring_through_Ethernet_network"><span class="mw-headline-number">4.2</span> Serial interfaces transferring through Ethernet network</span></h3>
<p>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 <b>socat</b> or <b>remserial</b>, <b>ser2net</b>, which can be built and run on the remote machine. Examples of throwing over the serial port:
</p>
<div class="mw-highlight mw-content-ltr" dir="ltr"><pre><span class="c"># Creating a socket on port 5555 on the remote computer, for the serial port /dev/ttyS0</span>
socat tcp-l:5555,reuseaddr,fork file:/dev/ttyS0,raw
<span class="c"># Connecting to the socket of the reflected port of the remote machine and creating a file of the mirrored local interface.</span>
socat -d -d pty,raw,echo<span class="o">=</span>0,perm<span class="o">=</span><span class="m">0666</span> tcp:192.168.2.4:5555,mss<span class="o">=</span>1400
<span class="c">#2013/07/04 10:09:09 socat[12947] N PTY is /dev/pts/4</span>
<span class="c">#2013/07/04 10:09:09 socat[12947] N opening connection to AF=2 192.168.2.4:5555</span>
<span class="c">#2013/07/04 10:09:09 socat[12947] N successfully connected from local address AF=2 192.168.2.61:33493</span>
<span class="c">#2013/07/04 10:09:09 socat[12947] N starting data transfer loop with FDs [3,3] and [5,5]</span>
</pre></div>
<p>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.
</p><p><a class="image" href="http://oscada.org/wiki/File:At.png"><img alt="At.png" height="22" src="../files/At.png" width="22" /></a> 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 <a href="../Modules/Sockets.html" title="Special:MyLanguage/Modules/Sockets">Transport.Sockets</a>. It is important that the value of this timeout in <a href="../Modules/Sockets.html" title="Special:MyLanguage/Modules/Sockets">Transport.Sockets</a> is greater than in the driver, otherwise it is possible to shift and receive delayed replies from previous queries.
</p><p>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:
</p>
<ul><li> <a class="external text" href="http://www.icpdas.com" rel="nofollow noreferrer noopener" target="_blank">ICP DAS</a>: <a class="external text" href="http://www.icpdas.com/products/Industrial/pds/tds-700.htm" rel="nofollow noreferrer noopener" target="_blank">tDS-7xx</a> — configures by WEB-interface and works straight on connection to TCP-port;</li>
<li> <a class="external text" href="http://tibbo.com" rel="nofollow noreferrer noopener" target="_blank">Tibbo</a>: <a class="external text" href="http://tibbo.com/products/controllers/ds100.html" rel="nofollow noreferrer noopener" target="_blank">DS100</a> — <span style="color: red">configures only by a program for MS Windows®</span>, provides self driver for virtual serial interfaces preparing on Linux, works straight on connection to TCP-port.</li></ul>
</div><table style="border-top: dotted 2px #999999; margin-top: 20pt; color: gray;" width="100%"><tr><td style="text-align: left;" width="40%"><a href="http://oscada.org/wiki/Modules/Serial/en">Modules/Serial/en</a> - <a href="http://oscada.org/en/main/about-the-project/licenses/">GFDL</a></td><td style="text-align: center;">April 2025</td><td style="text-align: right;" width="40%">OpenSCADA 1+r3018</td></tr></table></body>
</html>