This document describes the installation, usage, and functionality of a TLM (TOPDOC Loadable Module) for SoftPLC version 4.x and later. The TLM implements several TLIs (TOPDOC Loadable Instructions) for use with serial ports. COMGENIUS can be used to perform bi-directional serial communications to devices via RS-232, RS-422, or RS-485 links. COMGENIUS supports up to 36 serial ports in a SoftPLC system.
SoftPLC Corporation's SoftPLC control software product employs a unique technology which lets C/C++ or Java language programmers add new ladder logic instructions to the instruction set. A loadable instruction of this type is called a TLI. TOPDOC, the ladder logic programming package which supports SoftPLC, automatically learns about new TLIs as it logs into a SoftPLC.
TLIs may be developed by any competent C/C++/Java programmer who has access to the SoftPLC C/C++/Java Programmer's Toolkit, a product readily available from SoftPLC Corporation. There are a number of Systems Integrators who are SoftPLC Partners who possess the requisite expertise. End users may also have this capability.
This document describes a number of TLIs, all which reside in a TLM (TOPDOC Loadable Module) that is provided at no charge with all SoftPLC licenses. The TLM described by this document is called COMGENIUS. COMGENIUS can be used to perform bi-directional serial communications to devices via RS-232, RS-422, or RS-485 links. COMGENIUS supports up to 36 serial ports in a SoftPLC system.
- is a TOPDOC Loadable Module that you write in C or C++. It can implement a driver and/or one or more ladder instructions. It is executable within SoftPLC only, so it must be downloaded.
- A custom written ladder instruction, meaning TOPDOC Loadable Instruction. A TLI can be written in C/C++ and reside in a TLM, or it can be written in Java and reside in a Modlet or Driverlet.
- is a serial port. The SoftPLC runtime and COMGENIUS both support up to 36 serial ports.
- is an 8 bit value.
- is a 16 bit value that can reside in a STRING element and holds an international UCS-2 (UNICODE) symbol. ASCII is a subset of UCS-2.
- STRING element
- is an array of 16 bit (international) characters up to 82 character in length. The SoftPLC runtime supports arrays of STRING elements called STRING files, where there may be up to 10,000 STRING elements in each file. Up to 10,000 files are supported in a SoftPLC runtime. This is a maximum total of about 100,000,000 STRING elements comprised of 8,200,000,000 UCS-2 characters.
- format string
- is used by the COMPRINT and STRPRINT TLIs and describes how to how to convert the TLI's input arguments to a sequence of characters for output to a serial port or to a STRING element.
- a whitespace character is any character that is one of: ' ' (blank), \t (tab), \n (line feed), \r (carriage return), \v (vertical tab), and \f (formfeed).
The TLIs whose names begin with "COM" take a parameter called port. The port number specifies which logical serial COM channel a TLI is to work on. Since COMGENIUS supports 36 ports, legal values for port are 0 through 35. The port number may be provided either as a constant or as a PLC datatable word containing the value. All supported ports may be concurrently active.
The TLIs included in COMGENIUS TLM are:
|COMPRINT||Outputs a packet of characters which is dynamically assembled using powerful string formatting.|
|COMSCAN||Receives a packet of bytes and automatically decomposes it into useful data fields located in INTEGER, FLOAT and/or STRING elements.|
|COMRCVCLEAR||Clears the input buffer for a port.|
|COMRCVSTS||Tells how many characters are in the input buffer for a port.|
|COMXMITCLEAR||Clears the output buffer for a port.|
|STRPRINT||Works like COMPRINT, but uses a datatable resident destination STRING element instead of using a port. Outputs a string of characters using powerful string formatting.|
|STRSCAN||Works like COMSCAN, but uses a datatable resident STRING element instead of characters in a port buffer. Automatically decomposes a STRING into useful data fields located in INTEGER, FLOAT and/or STRING elements.|
- TOPDOC NexGen version 1.3.06xxxx or later, since there were some mandatory ehancements made in early 2006 which dealt with STRING parameters during instruction entry.
- Version 4.x SoftPLC or later.
- Serial Ports. CPU offerings from SoftPLC Corp. come standard with COM1 and sometimes COM2 depending on the platform. COM3-COM36 can only be used if you have one or more supported serial port expansion cards installed in the system. Check with tech support at SoftPLC Corp. for a list of supported serial port expansion cards available from SoftPLC for your platform.
Changes in 4.x
This TLM was substantially re-written since version 3.x SoftPLC, where it was known as COMGENIE. Below are the major changes from the 3.x version:
- All configuration information is now given in a single text file called COMGENIUS.LST. Information that was in the STRINGS.TXT file must be moved into COMGENIUS.LST. (This can be done with a simple cut and paste operation.)
- Internally, format strings are comprized of 16 bit characters. So although COMGENIUS.LST is an 8 bit ASCII file, any arbitrary UCS-2 character may be put into a format string by using the unicode escape sequence, which is like \uHHHH where the Hs are hex characters 0-9 and A-F or a-f. For example, the sequence \u000a is an ASCII line feed. Unicode escapes are an extension of the single byte hex escape, which have always been supported and still are, \xHH.
- The special format string escape \n is now interpreted as a line feed character, and not a carriage return linefeed combination as before. If you are converting from 3.x, you may have to do a search and replace on your format strings, changing \n with \r\n.
- The port configuration information is now also in the COMGENIUS.LST file and not on the module command line as before.
- STRING datatable elements are now required for COMPRINT or COMSCAN instructions where the corresponding format string is using %s. This is easier to work with, but might require some logic changes since you may no longer print a string contained in an integer file.
- The MEMCOMPARE TLI has been dropped. For comparing integers and floats, EQU or CMP may be used. For comparing STRINGS, use the ASR instruction instead.
- Since characters in a SoftPLC STRING element are 2 bytes wide and serial communications often requires 8 bit characters, now an encoding parameter is used to specify how to convert from the 16 bit STRING characters to the serialized data stream. This is specifiable per port and the chosen encoding methodology applies to both sending and receiving characters, but receiving bytes is the reverse of sending bytes as far as the encoding methodology is concerned.