serFrameReceiver (Functionblock)

serFrameReceiver reads a frame of data from the serial port. A "frame of data" is identified by a frameStart character and a frameEnd character. The frameStart character starts the reception, and the frameEnd ends the reception. After the frameEnd character has been received, the buffer (given in "frame") will contain the received data (excluding the frameStart and frameEnd characters). This function block is able to restore the data transmitted by the serSendData() function. If the "sof" (start of frame) character is set to 0, the reception will start with the first character and be terminated with the "eof" character.

When the data has been processed by the application, the function serFrameReceiveDone() must be called to release the receive buffer.

All RTCU devices contain a 16 KByte receive buffer for each of the serial ports available.

Input:

port : SINT (0..127) (default 0)

Selects which serial port to use.

enable : BOOL (Default FALSE)

Set to true if receiving data should be enabled.

frame : PTR

Address of the buffer to receive the data in.

maxSize : INT

This is the maximum size of the receive buffer.

sof : SINT

Start of frame character (indicates when a frame begins). Set to 0 to ignore start character.

eof : SINT

End of frame character (indicates when a frame ends). If set to 0, "maxSize" indicates number of characters to read (excluding the "sof" character).

stuffch : SINT

A duplicated "stuffch" in the data stream will be translated to a single "stuffch". A "stuffch" followed by a "sof" or "eof" will be translated to a "sof"/"eof". If "stuffch" is 0, the stuffing is disabled.

Output:                

ready : BOOL

True if a complete frame has been received (the minimum being that the frameStart and frameEnd characters have been received).

size : INT

Number of bytes received (excluding the frameStart and frameEnd characters).

Declaration:

FUNCTION_BLOCK serFrameReceiver;
VAR_INPUT
  port     : SINT := 0;     // Port number
  enable   : BOOL := FALSE; // enabled?
  frame   : PTR;          // ptr to frame memory  
  maxSize : INT;         // max size of frame.
  sof     : SINT;         // frame start indicator. Can be 0 for not used. SOF is implicit on first byte.
  eof     : SINT;         // frame END indicator. Can be 0 for not used. Will read maxSize chars.
  stuffch : SINT;         // stuffing character
END_VAR;
VAR_OUTPUT
  ready   : BOOL;         // data is ready  
  size     : INT;         // actual size of received frame.
END_VAR;

Example:

INCLUDE rtcu.inc
 
VAR_OUTPUT
  led     : BOOL; | Indicates that a serial frame has been received
END_VAR;
 
PROGRAM test;
 
VAR
  RX       : serFrameReceiver;
  rxbuffer : ARRAY[0..63] of SINT; // Declare a buffer for receiving frames from the serial port
  txbuffer : ARRAY[0..63] of SINT; // Declare a buffer for sending frames to the serial port
  portNum : SINT := 0;                   // Select which port to use for the communication        
END_VAR;
 
// Open the serial port, set baudrate, parity and number of bits
serOpen(port:=portNum, baud:=9600, bit:=8, parity:=0);
// Enable receiving from the serial port, data will be stored in 'rxbuffer', start of frame is a <CR> and end of frame is a <LF>
RX(port:=portNum, enable:=TRUE, frame:=ADDR(rxbuffer), maxSize:=SIZEOF(rxbuffer), sof:=16#0D, eof:=16#0A);
 
// Send the string <CR>ABC<CR><LF> using a buffer
txbuffer[0]:=16#0D; // <CR>
txbuffer[1]:=16#41; // 'A'
txbuffer[2]:=16#42; // 'B'
txbuffer[3]:=16#43; // 'C'
txbuffer[4]:=16#0D; // <CR>
txbuffer[5]:=16#0A; // <LF>
serSendData(port:=portNum, data:=ADDR(txbuffer), size:=6);
 
// Send a <CR>
serSendChar(port:=portNum, ch:=16#0D);
// Send the string 'Hello world'
serSendString(port:=portNum, str:="Hello world");
// Send a <CR>
serSendChar(port:=portNum, ch:=16#0D);
// Send a <LF>
serSendChar(port:=portNum, ch:=16#0A);
 
BEGIN
  // Allow the receive functionblock to be updated
  RX();
  // Check if a frame has been received (at least a <CR> and a <LF> has been received)
  IF RX.ready THEN
     // Indicate a frame has been received, data is available in 'rxbuffer', length in 'RX.size'
     led:=NOT led;
     // Here we do something with the frame that has been received
     // ..
     // ..
     // ..
     // Release the buffer for the receiver as we are now finished with the received data
    serFrameReceiveDone(port:=portNum);
  END_IF;
END;
 
END_PROGRAM;