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>

CNTxInternal counter, where x = counter <id> (1–5)

Constant

Value to be used for comparison with paramX

NFGGSM / 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

$CNT1Counter 1 value
$CNTxCounter x value (1–5)
$CON1Condition 1 result value
$CONxCondition 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"