====== Receive SMS ======

{{:en:mervis-ide:35-help:receivesms.png}}

===== Block name =====

RECEIVESMS

===== ST call =====

<code st-iec>
TYPE KRATKY_STRING : STRING[160]; END_TYPE
PROGRAM TEST_RECEIVESMS
VAR_OUTPUT
    SMSRES : INT := 0;
    SMS_RECEIVE : BOOL := FALSE;
    SMS_CHANNEL : ARRAY[0..9] OF STRING;
    SMS_SENDER : ARRAY[0..9] OF KRATKY_STRING;
    SMS_MESSAGE : ARRAY[0..9] OF STRING;
    RECEIVE_TIME : ARRAY[0..9] OF DT;
    RESULT : ARRAY[0..9] OF INT;
    I : INT := 0;
END_VAR

IF SMS_RECEIVE THEN
    FOR i := 0 TO 9 DO
        RESULT[I] := MESSAGING.RECEIVESMS(CHANNEL => 
        SMS_CHANNEL[I], SENDER => SMS_SENDER[I], MESSAGE => 
        SMS_MESSAGE[I], RECEIVETIME => RECEIVE_TIME[I]);
    END_FOR;
    SMS_RECEIVE := FALSE;
END_IF;
MESSAGING.SENDSMS();

END_PROGRAM
</code>

===== Library =====

MESSAGING

===== Version =====

V1.0

===== Description =====

The function asks the connected modems for received SMS messages in each PLC computing cycle. This function **shall be used in ST code only**, so that the function is called only if the incoming SMS status shall be checked.

===== Outputs =====

|Output     |Type  |Description                                        |
|=>         |INT   |numeric status; result of the system settings check|
|CHANNEL    |STRING|channel at which the SMS modem is connected        |
|SENDER     |STRING|SMS message sender number                          |
|MESSAGE    |STRING|received SMS message text (ASCII)                  |
|RECEIVETIME|DT    |time of SMS receiving                              |

===== Function =====

The //receivesms// checks the connected modem for SMS messages. The output is the channel number //channel// from which the message was read, message sender number //sender//, time when the SMS was received //receivetime//, the SMS message itself //message,// and result of reading.

The //channel// variable refers to the defined communication connection. This must be created in the PLC Properties menu: doubleclick the PLC and select //Message definition//, then right-click the context menu and //Add alarm channel//.

{{:en:mervis-ide:35-help:sendmail_1.png}}

Now, define the channel name which is the value of the //channel// variable. Then, the GSM connection type must be defined: click to select the channel and set the port to communicate to the modem in the channel properties. Set the channel communication properties. If the SIM card is secured by a PIN, enter the PIN here. Finally, confirm all changes by clicking OK in the red dialogue.

{{:en:mervis-ide:35-help:sendsms_1.png}}

If some of the predefined modem types is used, like Siemens TC-35 chipset, or Wavecom, it is possible to set in the //AT command settings// predefined commands to set up the modem. Then click the //Apply// button. The necessary AT commands are then added to the table. Click the //Close// button and confirm by clicking OK in the red dialogue. If another modem type is used, the AT command sequence has to be entered manually. (In case of unsupported modem types please contact the Domat Control System technical support.)

{{:en:mervis-ide:35-help:sendsms_2.png}}

The output variable //result// indicates the result of the system settings check.

|Value|Description                                                                        |
|0    |OK                                                                                 |
|16   |Unknown channel                                                                    |
|24   |Error - impossible to determine the status                                         |
|25   |Port can not be opened or modem can not be initialised (e.g. wrong COM port number)|
|26   |Timeout at the AT command (default 2 s)                                            |
|31   |No message                                                                         |
|42   |GSM channel error (e.g. wrong PIN, network not available …)                        |
|other|Internal error - contact Domat Control System support                              |

===== Application example =====

This function may be used to enter a string to the PLC using a SMS message. See ST call above. Standard number of 10 storage positions is used, where the received SMS messages are stored. All corresponding positions in the //sms_receive, sms_channel, sms_sender, sms_message, receive_time, and result// variables are parameters of a single SMS message. Currently read SMS messages have 0 in //results//. If there is another value on any of the //results// position, the SMS message could not be read from this position and in the corresponding //sms_receive, sms_channel, sms_sender, sms_message// and //receive_time// fields are either empty, or they contain the last message which was stored there. Maximum SMS length is 160 characters.