gsmIncomingSMS (Functionblock)

Use this function block to check whether there is an incoming SMS message from the cellular network or over the RTCU Communication Hub.

The device has a buffer where SMS and PDU messages are stored. To prevent loss of any messages, this buffer can only contain one message at a time.

Since this buffer is shared between SMS and PDU messages, it is possible if a PDU type SMS message is received and no instance of the gsmIncomingPDU is present in the application that this incoming PDU message will block the possibility of other SMS messages arriving. Because of this, it is recommended to have an instance of the gsmIncomingPDU even if the application is not normally expecting PDU messages.

The buffer will not be filled until either gsmIncomingSMS or gsmIncomingPDU is called.

The GSM network handles the concatenated messages by splitting it up into smaller pieces, which is then send as a standard SMS messages with information on how to assemble the original text again.

Since the concatenated text can be larger than the maximum size of a string, the gsmIncomingSMS returns the smaller pieces with the necessary information to assemble the original text again.

An SMS message sent from the RTCU IDE (or any other RACP-compliant peer) that uses a cable or data connection will be delivered to the application with the "phone number" set to "9999". See also gsmSendSMS.

Messages received through the RTCU Communication Hub will have the "phone number" set to the node number of the originating node prefixed with "@" (e.g. "@3917321112").

Note: the phone book on the used SIM card must be empty. If a caller that is present in the phone book sends an SMS message, this message will not be delivered to the program.

Input:

None.

Output:

status : INT (0..2)

phonenumber : STRING

Caller id of the sender (if status is 1).

If the number is prefixed with a "@", the message is received through the RTCU Communication Hub and the number after the "@" character is the originating node number (only supported in network-enabled devices).

The "phone number" will be set to "9999" for messages sent from the RTCU IDE (or any other RACP-compliant peer).

message : STRING

Message from the sender (only if status is 1 or 2).

reference : DINT

The reference ID that identifies which message the received message fragment is part of. (only if total is more than zero)

number : INT

The part number in the sequence of the received message fragment. (only if total is more than zero)

total : INT

The total number of parts in the message. (only if status is 1 or 2)

Declaration:

FUNCTION_BLOCK gsmIncomingSMS;
VAR_OUTPUT
  status     : INT;
  phonenumber : STRING;
  message     : STRING;
  reference   : DINT;
  number     : INT;
  total       : INT;
END_VAR;

Example:

INCLUDE rtcu.inc
 
PROGRAM test;
 
VAR
  incoming : gsmIncomingSMS;
END_VAR;
 
BEGIN
  incoming();
  ...
  // Check for incoming calls
  IF incoming.status = 1 THEN
     // Somebody with a callerid has sent us a SMS message
     // Set the current write position to 1,1 (leftmost, first row)
    displayXY(x:=1, y:=1);
     // Print the received callerid in the display
    displayString(message:=incoming.phonenumber);
     // Set the current write position to 1,2 (leftmost, second row)
    displayXY(x:=1, y:=2);
     // Print the received SMS message in the display
    displayString(message:=incoming.message);
     ...
  END_IF;
END;
 
END_PROGRAM;