Anders Danielsson Serial COM Port To TCP/IP

30 March 2018, 72.10 KB.

ReadMe

AdComTcp - Anders Danielsson Serial COM Port To TCP/IP Copyright © 2018 Scandinavian Digital Systems AB Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. --- INSTALLATION -------------------------------------------------------------- Make sure you have Microsoft .NET Framework 3.5 SP1 or newer installed. It is usually already installed in Windows 7 and Server 2008 R2, or newer versions of Windows. There is no installation program, you have to do the installation manually. Copy all included files to a folder (directory) where all user accounts running "AdComTcp.exe" have full security permissions of files and folders, including the local system account (SYSTEM) if running AdComTcp as a service. All files and folders under the installation folder must inherit this full permission, because AdComTcp will create new files using the inheritance. If you are unsure about setting security permissions, create the folder "C:\Users\Public\Documents\AdComTcp" and unzip all included files to it. Usually, this folder will have sufficient permissions. All configurations and settings are read by AdComTcp from the file "AdComTcp.Config.txt" in the same folder as "AdComTcp.exe". "AdComTcp.Config.txt" is not included in the zip file, so you may update AdComTcp without overwriting your settings. First time installations may copy the included "AdComTcp.Config.New.txt" to "AdComTcp.Config.txt" and then modify it as needed with e.g. Notepad. Latest version of AdComTcp may be downloaded at: http://www.digsys.se/ --- EXECUTING ----------------------------------------------------------------- Open a Command Prompt (as an administrator), go to the installation folder and run "AdComTcp" without any arguments and the following help will be displayed: AdComTcp {command} {command} is one of: install Install the Windows Service. uninstall Uninstall the Windows Service. start Start the Windows Service. stop Stop the Windows Service. status Display status of the Windows Service. idlestop Request stop of the Windows Service when idle. idleabort Abort the idle stop request. idlewait m Use Idle Stop and wait up to m minutes until Stop. console Run the Windows Service as a console application. help Display this help. Windows Service changes may require administrator privileges. Sets ERRORLEVEL to: 0 Success or Service is Stopped. 1 Service is Started (Running). 255 Error or failure. You may run AdComTcp as a plain console application using the command: AdComTcp console This may be useful when testing different configurations, or when no service installation is needed. To run AdComTcp as a Windows Service, you must first install it, using: AdComTcp install AdComTcp will then start on the next reboot, or you may use the command: AdComTcp start You may need administrator privileges to install/uninstall and start/stop AdComTcp as a service. When running AdComTcp as a service, it uses the local system account (SYSTEM) by default, but this may be changed by running "services.msc". When unzipping or copying a new version of AdComTcp.exe, the AdComTcp service must first be stopped. Even if AdComTcp will work with "Windows Fast Startup" enabled, it may cause problems if the computer is shutdown during communication. You should turn off (disable) "Windows Fast Startup" by unchecking the "Turn on fast startup" option in "Power Options" under "Choose what the power button buttons do", or disable hibernation altogether by using the command "powercfg /h off". Example of batch scripts to stop and start AdComTcp during e.g. maintenance or backup events: :StopAdComTcp echo Stopping AdComTcp... C:\Users\Public\Documents\AdComTcp\AdComTcp.exe idlewait 5 if %errorlevel%==0 exit /b 0 echo Error when stopping AdComTcp! exit /b 1 :StartAdComTcp echo Starting AdComTcp... C:\Users\Public\Documents\AdComTcp\AdComTcp.exe start if %errorlevel%==1 exit /b 0 echo Error when starting AdComTcp! exit /b 1 --- USAGE --------------------------------------------------------------------- AdComTcp relays all communication between serial ports and TCP/IP sockets. The TCP/IP socket may be a raw TCP/IP or a Telnet port. The Telnet port may use RFC-2217 Telnet Com Port Control Option. The serial port may be a hardware RS-232 port, USB adapter, or a virtual COM-port. Usually a null-modem emulator such as "com0com" is used. See: https://sourceforge.net/projects/com0com Wires and communication flow using com0com: CNCA0 Virtual serial port used by end user application CNCB0 Virtual serial port used by AdComTcp TCP RFC-2217 Telnet port used by AdComTcp, connected to a remote host CNCA0 ↔ CNCB0 ↔ TCP RXD ← TXD ← Inbound data TXD → RXD → Outbound data DTR → DSR → DTR (RFC-2217) DSR ← ON DCD ← DTR ← DCD (RFC-2217) RTS → CTS → RTS (RFC-2217) CTS ← RTS ← CTS (RFC-2217) RI ← OFF OFF → RI OFF → DCD N.C. ← DSR (RFC-2217) N.C. ← RI (RFC-2217) Currently, AdComTcp is only communicating as a DTE being the client part in RFC-2217. Future versions may include communicating as a DCE and being an RFC-2217 server. AdComTcp always uses 8 data bits, no parity and 1 stop bit (8N1). Future versions may include other parameters. AdComTcp also always uses CTS/RTS handshake, or actually, transfers the handshake between RFC-2217 and the COM-port. When the DSR input of the COM-port used by AdComTcp changes state (goes on or off), all transmit and receive buffers of both the COM-port and the TCP/IP socket are purged (deleted). This also happens when "com0com" is used with buffer overrun disabled and the other port is not opened or does not read the data. --- LOG ----------------------------------------------------------------------- Regardless of whether AdComTcp is running as a service or as a console application, it will always use the file "AdComTcp.Log.txt" as log output. "AdComTcp.Log.txt" is created in the same directory as "AdComTcp.exe", and the user account running "AdComTcp.exe" must have security permissions to do so. Other log files may also be used, as configured in "AdComTcp.Config.txt", but "AdComTcp.Log.txt" is the fail safe log file. "AdComTcp.Log.txt" shrinks automatically if it gets larger than about 256 kilobytes, no external maintenance is needed. All dates and times in "AdComTcp.Log.txt" uses UTC±00:00 and the ISO 8601 extended format "yyyy-MM-dd HH:mm:ss.fff". -------------------------------------------------------------------------------

Config

; ; "AdComTcp.Config.txt" is read by AdComTcp.exe at start-up. ; ; The encoding should be UTF-8. ; ; Any changes in this file will take effect only when AdComTcp is stopped and ; then started again. ; ; Any errors when reading this configuration file will be seen in ; "AdComTcp.Log.txt". ; DebugOutputToFiles=0 ; ; When set to 1, debug information will be outputted to "Port.N.Debug.txt", ; where N is the port number (index). These files are not maintained, and will ; grow forever. Performance may also decrease. The files are kept open, and can ; not be deleted or changed, unless AdComTcp is stopped. They may be read while ; AdComTcp is running. AdComTcp uses an internal small write buffer, that may ; delay file output, but the files are always flushed when everything is quiet. ; DebugEachByte=0 ; ; By default (0), individual received and transmitted bytes are not written ; to "Port.N.Debug.txt". If set to 1 then every byte will also be written ; in hexadecimal and ASCII. This may produce very large debug files. ; ClearDebugFilesAtStart=0 ; ; When set to 1, the "Port.N.Debug.txt" will be cleared (emptied) on start. ; The default (0) is to append debug information to the debug files if they ; exist. ; ExtendedErrorMessages=0 ; ; When set to 1, errors in the log file "AdComTcp.Log.txt" will have extended ; exception information. This may be useful for bug reports and during ; development. ; WaitSecondsBeforeFirstStart=5 ; ; Number of seconds (1 - 600) to wait before starting the first time after ; AdComTcp.exe is loaded. This delay may be needed to allow "com0com" and ; other drivers to load and start. ; WaitSecondsAfterErrorException=60 ; ; Number of seconds (1 - 3600) to wait after severe errors until restarting ; again. If e.g. the socket get closed (disconnected) then the port task will ; close down everything, wait this time, and then restart again. This will ; repeat forever until AdComTcp is stopped. ; QuietSecondsUntilIdle=300 ; ; If everything is quiet for this number of seconds (1 - 86400), the port task ; will go idle. ; DsrOffSecondsUntilIdle=10 ; ; If everything is quiet and input DSR of the COM-port is off (disabled) for ; this number of seconds (1 - 86400), the port task will go idle. ; IdleSleepMilliseconds=100 ; ; Number of milliseconds (1 - 1000) to sleep at a time during idle. This will ; be the maximum response time when any activity starts on the serial port or ; on the network socket. When leaving idle, RFC-2217 Telnet Com Port Control ; Option initialization commands will be resent. ; ; ; Port.N settings: ; ; N is the port task number (index) from 0 to 99, inclusive. ; ; Port.N.EnableThisPort=1 ; Must be 1 for this port task to be active (in use). Default is 0. ; ; Port.N.SerialPort="CNCB0" ; Serial COM-port to use. ; ; Port.N.SerialBaudRate=115200 ; Baud rate of the serial COM-port, 50 - 4000000. ; Default for 'Port.0' is 115200. ; ; Port.N.HostName="192.168.1.100" ; Host name or IP address of remote TCP/Telnet server to connect to. ; Both IPv4 and IPv6 are supported. ; ; Port.N.PortNumber=23 ; TCP port number (1 - 65535) to use, default for 'Port.0' is 23 (Telnet). ; ; Port.N.EnableIAC=1 ; Enable Telnet "Interpret As Command" (IAC), including RFC-2217 Telnet Com ; Port Control Option. Default for 'Port.0' is 0, IAC disabled. ; ; Port.N.SslProtocol=TLS10 ; SSL/TLS protocol, one of: ; NOSSL No SSL/TLS protocol is used (default for 'Port.0'). ; NETSSL Use SSL 3.0 or TLS 1.0 protocol. ; SSL2 SSL 2.0 protocol. ; SSL3 SSL 3.0 protocol. ; TLS10 TLS 1.0 protocol. ; TLS11 TLS 1.1 protocol, only .NET Framework 4.5 or later. ; TLS12 TLS 1.2 protocol, only .NET Framework 4.5 or later. ; AdComTcp will ignore security results of the connection, but will write them ; to the log. ; ; Port.N.CertServerName="" ; Server name in certificates. If empty "" then 'Port.N.HostName' ; will be used. AdComTcp will ignore any errors, only write them to the log. ; ; Port.N.CheckCertRevocationList=0 ; Check certificate revocation list. Default for 'Port.0' is 0, no revocation ; list check. ; ; Port.N.PfxFile="mycert.pfx" ; Path and name of a PFX file. Default is to not use any personal ; certificates. PFX files may be created from PEM files using OpenSSL, e.g.: ; openssl pkcs12 -export -out mycert.pfx -inkey key.pem -in cert.pem ; -passout pass:mypass -certfile ca.pem ; ; Port.N.PfxPassword="mypass" ; Password of the PFX file. Default is no password. ; ; Port.N.SocketTransmitBufferSize=256 ; AdComTcp's output socket transmit buffer size in bytes (16 - 65536). This ; size must be less than the socket receiver's CTS/RTS overhead buffer, when ; RFC-2217 is used. If a continuous stream of bytes are received from the ; COM-port at very high speed (com0com does not emulate the baud rate), they ; will be transmitted to the TCP socket in whole blocks of ; 'SocketTransmitBufferSize' bytes at a time, so the receiving socket has no ; possibility to send "CTS Off" other than between these blocks. ; ; Port.N.SerialReceiveBufferSize=256 ; AdComTcp's input serial receive buffer size in bytes (256 - 65536). This size ; is usually set to match the 'Port.N.SocketTransmitBufferSize', to force ; CTS/RTS handshaking and limit the transfer speed. If the serial sender does ; not handle CTS/RTS well, this buffer size may need to be much larger. ; A standard Win32 COM-driver sets RTS On when the input buffer is less than ; 50% full, and sets RTS Off when the input buffer is more than 75% full. ; ; Port.N.SerialTransmitBufferSize=256 ; AdComTcp's output serial transmit buffer size in bytes (16 - 65536). This ; size must be less than the serial receiver's CTS/RTS overhead buffer. If a ; continuous stream of bytes are received from the TCP socket at very high ; speed, they will be transmitted to the COM-port in whole blocks of ; 'SerialTransmitBufferSize' bytes at a time. ; ; Port.N.SocketReceiveBufferSize=256 ; AdComTcp's input socket receive buffer size in bytes (256 - 65536). This size ; is usually set to match the 'Port.N.SerialTransmitBufferSize'. Setting this ; also sets the TCP/IP receiving window size. If the socket sender is sending ; large blocks of data at once, and does not use or handle RFC-2217 well, this ; buffer size may need to be much larger. ; ; The small size of 256 bytes on all buffers above is the default (for ; 'Port.0'). This will work with most applications, but may not give the best ; performance. ; ; All the buffer sizes above depends on the end applications at both the serial ; and socket sides. If both applications uses buffers larger than any ; transfered block of data, then CTS/RTS are in fact never used, and all above ; buffer sizes may be set to e.g. 2048 for better performance. ; ; Using "com0com" with the option "emulate baud rate", limits the speed of ; sending data out of that port to the other. This can change the communication ; very much. Buffers in that direction can (and should) then usually be larger. ; ; ; All 'Port.N' settings, except 'Port.N.EnableThisPort', are inherited from the ; previous port N-1. Only settings that are different from port N-1 needs to be ; set. ; ; Below is a sample setup with 4 ports: ; Port.0.EnableThisPort=1 Port.0.SerialPort="CNCB0" Port.0.SerialBaudRate=115200 Port.0.HostName="192.168.1.100" Port.0.PortNumber=7020 Port.0.EnableIAC=1 Port.0.SslProtocol=TLS10 Port.0.CertServerName="miniCom modempool" Port.0.CheckCertRevocationList=0 Port.0.PfxFile="C:\MCM\minicom.pfx" Port.0.PfxPassword="minicom" Port.0.SocketTransmitBufferSize=512 Port.0.SerialReceiveBufferSize=512 Port.0.SerialTransmitBufferSize=2048 Port.0.SocketReceiveBufferSize=2048 ; Port.1.EnableThisPort=1 Port.1.SerialPort="CNCB1" ; Port.2.EnableThisPort=1 Port.2.SerialPort="CNCB2" ; Port.3.EnableThisPort=1 Port.3.SerialPort="CNCB3" ;

Version

Version history of AdComTcp Version: Date (ISO): Comments: 1.0.0.1 2018-03-07 Started development of 'AdComTcp'. 2018-03-18 First release. 1.0.0.2 2018-03-20 Performance bugfix. 1.0.0.3 2018-03-29 Added inherited defaults of port configurations.
Copyright © 1996-2018 Scandinavian Digital Systems AB
Developed by Anders Danielsson