Functions for the async serial interface ("RS-232")

(only available for certain terminals with a special, modified implementation of the CANopen protocol)

This document describes how the terminal's asynchronous serial interface can be accessed through the interpreter. These functions can be used to communicated with remote equipment, like voltmeters with RS-232 interface, modems, etc. For GPS receivers, there is a separate decoder built inside the firmware (which is not the scope of this document).

Note: Only very few terminals support this function - see Feature Matrix : "serial port access") !
This feature must be unlocked (by the manufacturer, or via password) before using it .
The same applies to the script language - it must also be unlocked before you can use it to access the serial ports .

Contents

1. Display Interpreter functions and commands for the serial port(s)
   1. Configuration of the serial interface
   2. Reception
   3. Transmission
   4. Transmission of binary data blocks (requires special firmware, available since January 2007)
2. Script Language functions and commands for the serial port(s)
   1. Opening a serial port (using the script language's file I/O API)
   2. Receiving and sending text lines
3. Pinout of various serial port connectors
4. Appendix: An example for using the serial port with the display interpreter

See also:

• Manual for the programming tool (general)
• String processing functions in the interpreter
• Decoder for GPS / NMEA0183-sentences

1. Overview of display interpreter functions and -procedures for the serial interface

1.1 Configuration of the serial interface (baudrate, protocol, etc)

Screenshot of the serial port settings in the programming tool.
The serial port selected here will appear as device "serial1" in the simulation.

file.open("serial1/<baudrate>) (script command to open a "file", in this case a serial port)

This is the preferred method to open and configure a serial port. Use it whenever the script language is available (i.e. for anything except "MKT-View I").

ser.baud (old display interpreter command)

get or set the baudrate for the serial port. Unit is bit per second. Allowed values are 1200, 2400, 4800, 9600, 19200, and sometimes 38400 (bit/second). Caution, some targets don't support 38400 bit/sec. Other targets (especially ARM-CPUs with firmware compiled after 2010-02-09) support serial baudrates up to 115200, 230400, or even 460800 bit/second .
Example for switching the serial port's baudrate via interpreter command:
@ser.baud=19200
sets the baudrate for the serial port to 19200 bit/sec.

ser.prot (old display interpreter command)

selects the protocol used for the serial port. The parameter is a double-quoted string with the following meaning:
"OFF" = no characters are received or sent (from the application's point of view, the serial port is "unused"). This is the default state, for reasons explained here.
"CHARS" = single characters are immediately passed to the receiving functions (like ser.rstr).
"LINES" = data are transmittes as TEXT LINES, usually terminated with the carriage return character (code 13, see ser.term).
Characters will not be passed to the application until the termination character was received.
"3964R_LP" = 3964R protocol, low priority
"3964R_HP" = 3964R protocol, high priority

ser.term

specifies the ASCII-value termination-character, if ser.prot is set to "LINES". By default, ser.term=13 which is the carriage-return character (ASCII).

1.2 Reception

ser.rstr

retrieves the last received string (or block of characters) received from the serial port. If the protcol is set to "LINES", the received characters will not appear until the termination-character was received (in contrast to the ser.rbuf function).  The result is always a string value. Retrieving the received with this function does not automatically remove it from the buffer - instead you have to clear it by setting ser.rstr="" (empty string), or invoke the ser.clr command.
To convert the received string into numeric value(s), use the interpreter's eval-function (extended value parser). See examples in the appendix.

ser.rbin. ...

A group of commands and functions for the reception of binary data blocks (which may, in contrast to ser.rstr, contain any possible character code).

ser.rcvd

Checks if a certain string has been received, without removing it from the buffer. This function was intended to write simple RX-handlers, where different received strings (or commands) are be polled in the terminal's global or local event handlers. This function is not just a simple string-comparator, instead it also supports wildcards ("*"="any string") as in the following example:
ser.rcvd("$GPRMC*") will become TRUE, whenever a 'Recommended minimum specific GPS/Transit data' has been received from a GPS receiver in NMEA-0183 format. The event handler which would be called then could split the recevied message into time, latitude, longitude, and speed over ground as required.

ser.rclr

Clears the received string (ser.rstr). Often used in event-handlers to avoid multiple triggering of a single ser.rcvd-query: Clear the received string as soon as you have "handled" it. An example can be found in the appendix of this document.

ser.rbuf

retrieves the contents of the low-level input buffer. In contrast to ser.rstr, received characters will immediately be visible in this buffer as soon as they have been received, without waiting for the end of the block. This is useful if the received characters originate from an "ASCII-Terminal" where a human operator types them quite slowly, or for testing purposes.

ser.rbcnt

retrieves the number of characters currently in the low-level input buffer (ser.rbuf). Your application may poll this function to check if anything was received at all.

ser.clr (interpreter command, not a function - returns no value)

Clears the low-level input buffer (ser.rbuf) and the buffer for the last received string (ser.rstr). It is usually *not* necessary to call this from your application, because the buffers will initially be empty anyway. It may be required if your interpreter script does some kind of block-decoding by itself.

1.3 Transmission

ser.tx(<string-expression>) (interpreter command)

Sends a string of text characters through the serial port. Very flexible thanks to the interpreter's string-handling functions (only in certain terminals with 16-bit CPU, so *not* available for the UPT515 !). Some examples:
ser.tx(str("00.0",0.1*ti)+"\r\n")  sends a numeric value converted into a string (using the str-function), followed by carriage return + new line as terminator.

ser.tbin. ...

A group of commands and functions for the transmission of binary data blocks (which may, in contrast to ser.rx, contain any possible character code).

1.4 BINARY data blocks (reception and transmission)

For a special application, the reception and transmission of binary data block was implemented in a special terminal firmware. The following display interpreter commands (and functions) can handle binary data blocks sent or received via the terminal's asynchronous interface ("RS-232"). In this context, "tbin" means "transmit binary", and "rbin" means "receive binary".

ser.rbin.l (lower case L) = length of the received binary block.

The maximum block size is 256 bytes (or 8-bit-characters). To begin a new reception (after your application has processed the received data), set ser.rbin.l to zero. The next received characters will then be written to ser.rbin.b[0], ser.rbin.b[1],ser.rbin.b[2], ... etc .

ser.rbin.b[<n>] = accesses the <n>-the byte in the received binary block.

Note that like in the "C" programming language, array indices start at 0 (zero) !.

ser.rbin.dump : dump of the received binary block (in hexadecimal notation).

ser.rbin.send : sends(!) the previously received binary block (possibly after being modified through other commands)

ser.rbin.ti = number of milliseconds passed since the last byte was received (and appended to the binary block).

Can be used to detect the "end" of a transmission. In fact, this is often the only possibility because the firmware itself does not know when a block ends (because it doesn't know the protocol). Use this function in an event definition, like:
EVENT: (ser.rbin.l>20) && (ser.rbin.ti>500)  : REM 20 bytes received, and 500 milliseconds passed since last byte
REACTION: goto("ReceivedSomething")

Almost the same components are available to transmit binary blocks. The following commands can be used to assemble a block under interpreter control, which can be sent through the serial port.

ser.tbin.l (lower case L) = length of the transmitted binary block.

Must be defined before sending ! The maximum block size is 256 bytes (or 8-bit-characters).

ser.tbin.b[<n>] = sets the <n>-the byte in the transmittable binary block.

Note that like in the "C" programming language, array indices start at 0 (zero) !.

ser.tbin.dump : dump of the transmittable block (in hexadecimal notation).

Can also be used to define the transmit data in a single command - see examples further below.

ser.tbin.send : sends(!) the previously assembled binary block.

That means, the bytes ser.tbin.b[0].... ser.tbin.b[ser.tbin.l - 1] will be transmitted as fast as possible through the serial port ("RS-232").

Some examples for binary data blocks:

ser.tbin.dump=010203FF : REM fill the TX-block with 4 bytes (hex 0x01 0x02 0x03 0xFF)
ser.tbin = ser.rbin : REM copy received block into transmit block
ser.tbin.b[2]=0x12 : REM replace the 3rd(!) byte with hex 12
ser.tbin.b[1]=ser.tbin.b[0] : REM copy the 1st(!) receive byte into the 2nd(!) TX-byte
ser.tbin.send : REM send the binary block

Notes on the reception and transmission of binary data blocks over the serial port

Handling received data blocks is quite complicated with the UPT's global (or local) event definitions. To be honest, the terminal was never designed for such low-level processing. But at least, with the ser.rbin functions, you can detect if something was received, how many bytes were received, and you can access the received data byte-by-byte. Of course, you won't be able to implement complicated serial protocols this way - such a task requires a fully grown up programming language (which the terminal's interpreter is not).

2. Overview of script language functions and -procedures for the serial interface

The script language greatly simplifies the use of the serial port(s) for your own purpose (see details about the script language in another document).

Unfortunately, the script language is only available for devices with a 32-bit CPU, furthermore the file I/O functions which are used to access the serial ports from a script belong to the 'extended script functions' which must be unlocked before they can be used.

For details about the general use of the file I/O functions, please refer to the script language reference .

2.1 Opening a serial port (using the script language's file I/O API)

Use the file.open command, with a device name (instead of the filename) like "serial1" for the first serial port, or "serial2" for the second port.
These pseudo-filenames can optionally be extended with additional parameters, which instruct the system how to open a serial port:

handle := file.open("serial1/9600") // open the first serial port with 9600 bits/second

Note

If a serial port is configured as a 'LIN bus interface' as explained here, it should not be reconfigured by the application. For example, changing the baudrate while a LIN bus frame is being sent or received will cause unpredictable results.
LIN allows a maximum of 19200 bits/second, which is what the MKT-firmware uses by default if a serial port is selected as a LIN bus interface.

2.1 Receiving and sending lines of text with the script language

Use the file.read_line function to read the input stream from the serial port, line by line, separated with CARRIAGE RETURN characters (or CR + NL).

To send a line of text, use file.write, and add a carriage return + new line at the end of the line (Unix users will leave away the 'new line' character).

For a complete example, see the script language documentation. Don't miss the explanation of the 'Serial Port Demo'. It uses a script to shows all lines received from both serial ports on the LCD (at least for the MKT-View II, which has two serial ports which can be accessed from the script) :

3. Pinout of various serial port connectors

Standard 9-pole "D-sub" connector, female, usually found on the "DCE" side (modem, or "Null-Modem" cable).
Signals which are not available (or not always available) on the display terminal are written in parentheses in the table below .

Caution: The "GPS-Mouse-Port" on the MKT-View II is NOT COMPATIBLE with this RS-232 connector !

Standard 9-pole "D-sub" connector, male, usually found on the "DTE" side (for example, on the back of a PC).
Signals which are not available (or not always available) on the display terminal are written in parentheses in the table below .

Non-Standard 9-pole "D-sub" connector, female, used at the 'GPS-Mouse-Port' in the MKT-View II.

Caution: This "GPS-Mouse-Connector" on the MKT-View II is NOT COMPATIBLE with a standard RS-232 connector !

Appendix

Sample application for the serial interface

There is a small test file for the MKT-View which demonstrates some of the possibilities using only the display interpreter. You can load it from \programs\ser_test.cvt .

On the first display page, the configuration of the serial port is displayed, and the last received string is shown on the terminal's screen. Furthermore, you can send a test string from this page (which may be edited on the screen also).

The ser.rbuf function shows the buffer for the currently received (still "incomplete") line of text.
The ser.rsts function contains the last "complete" line.

In the lower part, a few test patterns for the ser.rcvd function are show. Watch the results when sending different strings to the terminal, which contain the string "hello" (only), "hello this is a test", and "this is a test". You will quickly get an impression how this function can be used to detect special patterns in the received text.

In the event definitions of this page, the terminal looks for the string "help" in the received data. If this string is detected, it calls(!) a different page, from which a short help text is transmitted through the serial port in response to the "help"-command.

Other event definitions on this page parse numeric values from the received data. For example, the variable 'X' will be set to the numeric value contained in the first 8 characters of a received string. By replacing the Event always by something like
ser.rcvd("$GPRMC*"), you may be able to parse navigation information from a GPS receiver (though for GPS/NMEA-0183, there is a specialized decoder in the terminal firmware, so you don't need the interpreter to decode GPS position data).

Notes on conflicting usage of the serial interface

Originally, the serial port was exclusively used to download the terminal application ("user program") through the PC's RS-232 interface. Since the serial port may now be occupied by the application, the terminal cannot (always) listen for commands from the PC. Why ?

The program download between PC and Terminal uses a block-oriented protocol for the serial port called "3964R". When you select "Send application to the terminal through the serial port", but the serial port is occupied by the application (as described in this document), the 3964R-handler may be passive to avoid interference with the protocol which your terminal-application uses (through appropriate interpreter commands). The PC will therefore never receive the expected response from the terminal .... and your terminal application will, at least, be "irritated" by the characters received from the serial port.

So what to do in this case, when your application occupies the terminal's serial port, but you want to download a new application through just this port ? The answer is:

• First, enter the terminal's "Main" system menu (by pressing the two keys), then
• select the function "Receive from RS232", then
• Start the program transfer on the PC

The terminal will reprogram the serial port for communication with the PC in this case, which includes the initialisation of the 3964R-protocol.

If the serial port is not occupied by the terminal-application (which is the default, see ser.prot), you don't necessarily have to use the system menu to activate the download.

File: ..?..\uptwin1\help\sercmd_01.htm
Author: W.Büscher, MKT Systemtechnik
Last modified: 2007-01-08 (ISO8601, YYYY-MM-DD)

back to top