3.5 User Defined Functions - UDF
UDF provides a user-defined set of conditions for the terminal that are necessary for the actions to be executed. 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
- Obey 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 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 is as follows:
AT^SCUDF="ADD","AIN1>=50:SMS P[+420123456789] m[alarm1] t[60]"
Caution
- Make sure that each command includes a condition (syntax), separator (:) and action to be executed ("<syntax>:<action>") to avoid a 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 with a code if necessary. Refer to the Error Codes subsection below for the list of available messages.
UDF Condition Setting
Basic UDF commands.
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 an OK message is received, the condition is listed and available. Therefore, mind that an SMS or TCP message can be sent or the relay can be activated immediately.
AT^SCUDF="CLEAR"
- The command clears all conditions from the terminal memory.
AT^SCUDF="REMOVE",<ID>
- The command clears the condition with the selected ID.
AT^SCUDF?
- The command writes out all the conditions saved.
AT^SCUDF=?
- The command displays 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, i.e. a range of values (0–1). Select the respective syntax to select one of the available setting options.
UDF can work with the following parameters:
<paramX> | Description |
AIN1 | Analogue input 1 |
AIN2 | Analogue input 2 |
| AIN3 | Analogue input 3 |
DIN1 | Digital input 1 |
DIN2 | Digital input 2 |
| DIN3 | Digital input 3 |
PUL1 | Pulse input 1 |
PUL2 | Pulse input 2 |
| PUL3 | Pulse input 3 |
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 | GSM / UMTS network failure |
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 SCPING is set to make the NFG syntax evaluate connection states correctly.
The following operators can be used for state 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 |
25 | 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 will automatically be 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 fail) in case PING fails or the IP address is not obtained during the time set by 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 compare 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
The action saves the condition result into the terminal memory for later use.
Note
- A typical condition saving AT command is as follows:
At^scudf="add","AIN1>50:SAVE"
REL1
The action controls the state of relay 1.
REL2
The action controls the state of relay 2.
Note
- A typical relay switching AT command is as follows:
At^scudf="add","AIN1>50:REL1 r[1]"
SMS
The action sends the defined SMS to the defined telephone number.
Note
- A typical SMS sending AT command is 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 the SMS action successfully.
TCP
The action sends the defined TCP message to the defined IP address and port.
Use Telnet for TCP sending.
Note
- A typical TCP sending AT command is 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 the TCP action successfully.
Warning
- Make sure that the TCP receiving server exists to avoid process slow-down due to the terminal waiting for the response from a non-existent server and not executing new actions.
CNT 1–5
The action controls all of the 5 internal counters.
Note
- A typical AT command for counter increment by 1 is 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 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.
Phone number
Set the phone number p[xx], where xx is the telephone number in the national or international format. Hence, enter p[123456789] or p[+420123456789].
Caution
- The phone number can be used for the SMS action only.
- Enter phone numbers consisting of 1–15 characters into the parameter.
Relay state
Set the relay contact position r[1 or 0].
1means 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 just 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 |
| $AIN3 | Analogue input 3 value |
$DIN1 | Digital input 1 value |
$DIN2 | Digital input 2 value |
| $DIN3 | Digital input 3 value |
$PUL1 | Pulse input 1 value |
$PUL2 | Pulse input 2 value |
| $PUL3 | Pulse input 3 value |
| $CNT1 | Counter 1 value |
| $CNTx | Counter x value (1–5) |
| $CON1 | Condition 1 result value |
| $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 where the ALARM value is:(the currently measured value).
The AT command is 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 used and 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–4294967 s.
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–4294967 s.
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. Thus, 1 defines one incrementation 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 parameter and number 4658 sets the counter value.
GSM Error Signalling
The terminal program includes a UDF – Network Fail GSM (NFG) condition, which monitors the state of mobile network connection. In case the mobile connection fails, an action can be initiated to warn the user. Or, the event can just be written into the counter.
The condition is evaluated as TRUE (i.e. network fail) in case the PING fails or the IP address cannot be obtained within the time interval set in [ at^scping="interval",<minutes> ]. Obtaining the IP address then cancels this state and the condition is then evaluated as FALSE.
The AT command is as follows:
at^scudf="ADD","NFG:rel1 r[1]"
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 | Phone number length error |
11 | UDF_RESP_ERROR_PHONE_NUMBER | Phone number not found or format not supported
|
12 | UDF_RESP_ERROR_IP_ADDRESS | IP address not found or format not supported |
13 | UDF_RESP_ERROR_IP_PORT | Invalid IP port |
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 | Invalid value format/range |
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 the NFG syntax in UDF or keep firewall connection if the terminal is in the STANDALONE mode.
at^scping="host","8.8.8.8"
- The command sets 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"
- The command tests configuration before saving. The currently changed value is always saved and thus no restart is needed during setting and function check.
at^scping="save"
- The command saves the changes.
at^scping="restart"
- The command restarts the function.
at^scping="srestart"
- The command saves the changes and resets the ping parameters immediately.
at^scping?
- The command displays the current interface values.
- SCPING: "HOST","8.8.8.8"
- SCPING: "INTERVAL",0
at^scping=?
- The command displays the interface setting options.
SCPING: "HOST","1-32"<br> SCPING: "INTERVAL",0-65534<br> SCPING: "TEST"<br> SCPING: "SAVE"<br> SCPING: "RESTART"<br> SCPING: "SRESTART"