rfReceive (Function)

rfReceive will listen for a package transmitted by rfSend from any peer node set up with the correct parameters.

A package will be received by rfReceive when the "receiver" parameter in rfSend of the peer node is equal to the ID as specified in the rfOpen function. Broadcast packages that have the ID=0 as their destination will be received.

Also refer to the RF Functions for additional details.

The package received will be placed in the buffer specified by the "data" parameter. The maximum size of the expected package to be received must be specified in the "size" buffer. Automatic truncation of the received package will occur in cases where the size of the incoming package is greater than the "size" specified. It is recommended to use a receive buffer of 60 bytes to avoid this situation.

Finally a "timeout" parameter is also specified. It allows the application to regain control within a time period in case no package has been received.

rfReceive will therefore block until a package in received, a timeout has occurred, or the interface is closed from another thread by calling rfClose.

When rfReceive returns, the ID of the peer node will be returned in "sender" and also information on whether the package was broadcast.

Input:                

data : PTR

Address of the buffer to receive the package.

size : INT ( 0 .. 32767 )

Maximum number of bytes to receive into buffer specified.

The buffer must be able to hold this number of bytes.

The number of bytes received will not exceed 60 but a larger buffer is allowed.

timeout : INT ( -1 .. 32767 ) ( default 5000 )

milliseconds to waiting for incoming packages. "-1" means wait forever.

Output:                

sender : INT

The ID used when rfOpen was called on the sender.

broadcast : BOOL

Whether the message was broadcast to all IDs or addressed directly to the ID used when rfOpen was called. See RF Functions for details.

Returns: INT

Declaration:

FUNCTION rfReceive : INT;
VAR_INPUT
  size     : INT;
  timeout  : INT := 5000; // milliseconds to wait for data
  data     : PTR;         // Address of the buffer to send
  sender   : ACCESS INT; // rf id of sending device
  broadcast: ACCESS BOOL; // is data send to all id's.
END_VAR;

Example:

INCLUDE rtcu.inc
 
VAR_INPUT
  send  : BOOL R_EDGE;
  echo  : BOOL;
END_VAR;
 
VAR_OUTPUT
  sending   : BOOL;
  receiving : BOOL;
  no_data   : BOOL;
END_VAR;
 
PROGRAM test;
VAR
  rc       : INT;
  data     : ARRAY[ 1 .. 60 ] OF SINT;
  size     : INT;
  msg      : STRING;
  my_id    : INT := 1;
  sender   : INT;
  broadcast: BOOL;
END_VAR;
  msg := strFormat(format := "Message from \1", v1 := my_id);
  rfOpen(id := my_id);
BEGIN
  IF sending THEN
    size := strLen(str := msg);
    strToMemory(dst := ADDR(data), str := msg, len := size);
    rc := rfSend(data := ADDR(data), size := strLen(str := msg));
    DebugFmt(message := "rfSend(...) = \1", v1 := rc);
  ELSIF receiving THEN
    rc := rfReceive(data := ADDR(data), size := SIZEOF(data), sender := sender, broadcast := broadcast);
    IF rc < 0 THEN
        no_data := NOT no_data;
    ELSE
        no_data := FALSE;
        size := rc;
        rc := rfSend(receiver := sender, data := ADDR(data), size := size);
        DebugFmt(message := "echo : rfSend(...) = \1", v1 := rc);        
    END_IF;
  END_IF;
  sending := send;
  receiving := echo;
END;
END_PROGRAM;