3.5 User Defined Functions - UDF
UDF provides a user–defined set of conditions for the terminal that are necessary for execution of the set actions. The conditions must be met to make it possible to send SMS/ TCP messages or set the relay position on the given terminal.
Up to 10 UDF conditions can be set for a terminal.
Each condition is evaluated continuously and, if True, the defined action will be executed. For re–execution, the condition must meet the False status or remain in the set status for a timer–defined period. Thus, SMS will not be sent at every iteration.
Caution
- Follow tht the timer t[xx] in seconds, where xx is the waiting time. Refer to the Timer subsection for de general programming principles while creating the conditions to avoid nonsensical syntaxes and/or repetition of identical conditions. Such meaningless statuses cannot be processed effectively due to a limited memory and power capacities of the terminal.
Set the conditions using the AT commands in the terminal configuration. Each AT command must include the condition syntax (<parameter1>sign<parameter2>) followed by the separator ':', action type and action parameters.
A typical AT commands looks as follows:
AT^SCUDF="ADD","AIN1>=50:SMS P[+420123456789]m[alarm1] t[60]"
Caution
- Make sure that each command includes the condition (syntax), separator (:) and action to be executed ("<syntax>:<action>") to avoid command setting error.
Caution
- The maximum length of an AT command is 80 characters.
Note
- Any error occurring during condition saving is signalled by the ERROR message and identified by a code if necessary. Refer to the Error Codes subsection below for the list of available messages.
Basic AT Commands
This subsection provides all the AT commands and parameters that can be used for setting of UDF conditions. The basic commands are described first and then their parts are explained. These are the basic commands for the 2N® SmartCom PRO UDF.
AT^SCUDF="ADD","<code>"
- The "ADD" command adds a condition to the list of conditions. The command section marked as the code is the condition itself. The terminal replies OK after saving.
Caution
- When the OK message is received, the condition will be listed and available for work. Therefore, mind that an SMS or TCP message can be sent or the relay can be activated immediately.
AT^SCUDF="CLEAR"
- Enter the command to clear all conditions from the terminal memory.
AT^SCUDF="REMOVE",<ID>
- Enter the command to clear the condition with the selected ID.
AT^SCUDF?
- Enter the command to list all the conditions saved.
AT^SCUDF=?
- Enter the command to display the setting options.
- ^SCUDF: "ADD","0–100"
- ^SCUDF: "REMOVE",1–10
- ^SCUDF: "CLEAR"
Supported Syntaxes
The condition parameters can be entered in variable ways. For universality, each of the parameters can be a digit, i.e. an analogue input value or a binary input (0–1). Set a specified syntax to select one of the available setting options.
The UDF can work with the following parameters:
<paramX> | Description |
AIN1 | Analogue input 1 |
AIN2 | Analogue input 2 |
DIN1 | Digital input 1 |
DIN2 | Digital input 2 |
PUL1 | Pulse input 1 |
PUL2 | Pulse input 2 |
CONx | Reference condition where x = condition <id> |
| CNTx | Internal counter, where x = counter <id> (1 - 5) |
Constant | Value to be used for comparison with paramX |
| NFG | Network Fail GSM / UMTS |
Caution
- The parameters that are listed as digits, i.e. AIN and PUL, which may be 0 – 100, or 0 – 4294967295, are converted to logic values as follows: if their value is 0, their state will be 0.
- Make sure that SC PING is set to make the NFG syntax evaluate connection states correctly.
The following operators can be used for evaluation:
<operator> | Description |
> | param1 is greater than param2 |
< | param1 is smaller than param2 |
== | param1 is equal to param2 |
>= | param1 is greater than or equal to param2 |
<= | param1 is smaller than or equal to param2 |
&& | Conjunction |
|| | Disjunction |
! | Negation |
Use the standard syntax, i.e. <param1><operator><param2>, to compare the measured value. However, you can just write <param1>. If you omit the operator and enter one parameter only, the parameter is automatically considered as logic even with AIN and PUL. When this parameter becomes effective, the set action will be executed.
Let us show you some syntax examples now.
AIN1>50 – the syntax will be marked true in case the value measured on AIN1 is higher than 50.
PUL2==2596 – the syntax will be marked true in case the value measured on the PUL2 counter is equal to the constant.
DIN1&&CON3 – the syntax will be marked true in case the DIN1 value is true and the reference condition is also true.
!AIN2 – the syntax will be marked true in case any value higher than 0 is measured on the input.
AIN1<=AIN2 – the syntax will be marked true in case the value measured on AIN1 is lower than the value measured on AIN2.
NFG - the syntax will be marked true (i.e. network failure) in case PING failed or the IP address was not obtained during the time set at at^scping="interval",<minutes>. When the IP address is obtained, the state will be cancelled and the condition will become FALSE. See below for the PING settings.
Caution
- If you use Negation, the parameter will be treated as a digital input! It cannot be expected, for example, that if 50 is measured on AIN1, -50 can be obtained after negation.
- To match two inputs use the absolute values obtained from the converter (ADC 0 - 1020). Therefore, make sure that the two inputs have been calibrated properly.
Action Types
Insert an action after the separator for the selected syntax.
SAVE
Enter SAVE to save the condition result into the terminal memory for later use.
Note
- A typical condition saving AT command looks as follows:
At^scudf="add","AIN1>50:SAVE"
REL1
The action controls the relay 1 state.
REL2
The action controls the relay 2 state.
Note
- A typical relay switching AT command looks as follows:
At^scudf="add","AIN1>50:REL1 r[1]"
SMS
Enter SMS to send the defined SMS to the defined telephone number.
Note
- A typical SMS sending AT command looks as follows:
At^scudf="add","AIN1>50:SMS p[+420123456789] m[text 1]"
Caution
- Make sure that the telephone number and message parameters are completed to set this function successfully.
TCP
Enter TCP to send the defined TCP message to the defined IP address and port.
Use telnet for TCP sending.
Note
- A typical TCP sending AT command looks as follows:
At^scudf="add","AIN1>50:TCP i[62.134.22.87:8026] m[text 1]"
Caution
- Make sure that the telephone number and message parameters are completed to set this function successfully.
Warning
- Make sure that the TCP receiving server exists to avoid process slow–down due to the terminal waiting for the reply from a non–existent server and not executing new actions.
CNT 1-5
Enter CNT 1-5 to control all of the 5 internal counters.
Note
- The AT command for counter increment by 1 can be as follows, for example:
At^scudf="add","AIN1>50:CNT1 d[1]"
Action Parameters
Use the parameters of the actions mentioned above to change the relay states and set the address for SMS/TCP sending. Enter the parameters in the format <mark>[value] and separate them with a space on both ends. There is no specified order for the parameters.
IP address
Set the IP address i[xxx.xxx.xxx.xxx] and default port 80 for the TCP messages. To change the port, enter i[xxx.xxx.xxx.xxx:yyyyy], where x is the IP address of the remote server and y is the port to be used for TCP sending.
Caution
- Enter the IP address for the TCP action only as it is meaningless and signalled as error for the other actions.
Telephone number
Set the telephone number p[xx], where xx is the telephone number in the national or international format. Hence, enter p[123456789] or p[+420123456789].
Caution
- The telephone number can be used for the SMS action only.
- Enter telephone numbers consisting of 1 – 15 characters into the parameter.
Relay state
Set the relay contact position r[1 or 0].
1 means that the relay is closed and 0 means that the relay is open.
Caution
- The r parameter can be used for the REL action only.
Timer
Set the timer t[xx] in seconds, where xx is the waiting time. Refer to the Timer subsection for details.
Caution
- The timer can be used for the TCP and SMS actions only.
Message
Set the message m[text]. The maximum message length is 40 characters. Longer messages will be rejected.
Note
- The maximum of 40 characters is derived from the maximum length of the SMS to be sent. If the maximum PUL key values are used, the length is 160 characters.
Caution
- The message can be used for the TCP and SMS actions only.
You can also insert the following keys into the message parameter to show the value currently measured on the input circuits or the current logic value of the conditions in the SMS.
Key | Description |
$AIN1 | Analogue input 1 value |
$AIN2 | Analogue input 2 value |
$DIN1 | Digital input 1 value |
$DIN2 | Digital input 2 value |
$PUL1 | Pulse input 1 value |
$PUL2 | Pulse input 2 value |
| $CNT1 | Counter 1 value |
| $CNTx | Counter x value (1-5) |
| $CON1 | Condition 1 result value 1 |
| $CONx | Condition x result value (1-10) |
Let us show you an example for illustration.
Suppose you want to enter a command into the terminal, which, when the limit value 80 on input 1 is exceeded, will send an SMS to number 123456789 including the ALARM value is: (the currently measured value).
The AT command looks as follows:
AT^SCUDF="ADD","AIN1>80:SMS p[123456789] m[ALARM value is:$AIN1]"
The following SMS will be sent to the set number:
ALARM value is:87
Caution
- Should you enter an invalid or incomplete key, the key will not be included in the SMS sent.
Tip
- Enter a special key $$ to display the $ character in the SMS as the single $ character introduces other keys.
Timers
There are three ways how to make use of condition timing. See below.
Timer not set
The action is executed when the condition is evaluated as true. For re–execution, the condition must be false and then true again.
Timer
Set the t[60] string, where t identifies a timer. Number 60 is the timer delay in seconds. The timer setting options are 5 – 4294967s.
The action is executed when the condition is evaluated as true. For re–execution, the condition must be false and then true again, and the set timeout must be over.
Continuous timer
Set the t[c120] string, where t identifies a timer, c indicates a continuous timer and number 120 is the timer delay in seconds. The timer setting options are 5 – 4294967s.
The action is executed when the condition is evaluated as true. The action is re–executed after the timeout if the condition is true. The condition need not be evaluated as false before re–execution.
Counters
There 5 virtual counters altogether in the terminal program for counting actions or storing current values for later computation. The following two parameters are used for control:
Counter incrementing
Enter string d[1]. The 'd' parameter defines that the counter value increases by the value included in the brackets (one step). You can enter 1, 5, 254, etc. and also negative values, which will be subtracted from the set value.
Counter setting
Enter string s[4658]. The 's' parameter defines the counter setting value and number 4658 sets the counter value.
Error Codes
This table includes the error codes you can use for UDF setting. An incorrect command is signalled by ERROR <err_code>. The table helps you identify the type of error.
<err_code> | Name | Description |
1 | UDF_RESP_ERROR | General error |
2 | UDF_RESP_ERROR_NO_FREE_SLOT | No space for new record |
3 | UDF_RESP_ERROR_SYNTAX_ACTION_SEPARATOR | Separator ':' not found |
4 | UDF_RESP_ERROR_SYNTAX_LOGIC_MARK | Logic mark not found or wrong |
5 | UDF_RESP_ERROR_SYNTAX_PARAM1 | Condition parameter 1 not found or wrong |
6 | UDF_RESP_ERROR_SYNTAX_PARAM2 | Condition parameter 2 not found or wrong |
7 | UDF_RESP_ERROR_SYNTAX_INVALID_CONDITION | Condition not supported |
8 | UDF_RESP_ERROR_SYNTAX_ACTION | Action syntax error |
9 | UDF_RESP_ERROR_SYNTAX_ACTION_TYPE | Action type not supported |
10 | UDF_RESP_ERROR_PHONE_NUMBER_LEN | Telephone number length error |
11 | UDF_RESP_ERROR_PHONE_NUMBER | Telephone number not found or not supported |
12 | UDF_RESP_ERROR_IP_ADDRESS | IP address not found or not supported |
13 | UDF_RESP_ERROR_IP_PORT | IP port wrong |
14 | UDF_RESP_ERROR_RELAY_STATE | Relay state not found or not supported |
15 | UDF_RESP_ERROR_PARAM_PARSE | Action parameter translation error |
16 | UDF_RESP_ERROR_PARAM_MARK | Unknown action parameter type |
17 | UDF_RESP_ERROR_PARAM_MARK_TIMING_PERIOD | Timing period wrong or beyond limits |
18 | UDF_RESP_ERROR_PARAM_MESSAGE_LENGTH | Message length error |
19 | UDF_RESP_ERROR_ID_NOT_FOUND | Reference condition ID not found |
20 | UDF_RESP_ERROR_PARAM_TYPE_INVALID | Action parameter not supported for selected action type |
21 | UDF_RESP_ERROR_ACTION_IN_PROGRESS | Condition action in progress |
22 | UDF_RESP_ERROR_MESSAGE_MISSING | Message to be sent not found |
| 23 | UDF_RESP_ERROR_PARAM_VALUE | Value format or range is invalid |
SC Ping
Enter the commands to set periodical pinging to the set address in defined intervals. Use SC Ping to ensure the correct function of NFG syntax in UDF or keep firewall connection if the terminal is in the STANDALONE mode.
at^scping="host","8.8.8.8"
- Enter the command to set the Host IP address to which the ICMP request shall be sent.
at^scping="interval",5
- Enter the interval in minutes. 0 means that periodical pings are deactivated.
at^scping="test"
- Enter the 'test' command to test configuration before saving. The currently changed value is always saved and thus no restart is needed during setting and functionality check.
at^scping="save"
- Enter the command to save the changes.
at^scping="restart"
- Enter the command to restart the function.
at^scping="srestart"
- Enter the command to save the changes and reset the ping parameters immediately.
at^scping?
- Enter the command to display the current interface values.
- SCPING: "HOST","8.8.8.8"
- SCPING: "INTERVAL",0
at^scping=?
- Enter the command to display the interface setting options.
SCPING: "HOST","1-32" SCPING: "INTERVAL",0-65534 SCPING: "TEST" SCPING: "SAVE" SCPING: "RESTART" SCPING: "SRESTART"