Ausdrücke / Skriptsprache

Multi-line scripting language with syntax highlighting, usable in smart rules Equation, Formula and Script, and also in Modbus and Packet parser interfaces.

Basics

Association

Mu := Se + 2;

Multi-line algorithm

Each line is divided by semicolon

Last := Current;
Current := 0;

Returned value

Result of last line of code
RETURN(expression) stops execution of algorighm and returns content inside brackets

(Co2 > 800) AND (Wind < 10);
equals:
RETURN((CO2 > 800) and (Wind < 10));

Temporary variable

Lives within the single execution of the script.

VAR X := 5;

IF clause

Excel style

IF(logical_expression, value_if_true, value_if_false);
IF(logical_expression, value_if_true);

Multi-line style

IF X < 5
  RETURN(1);
ELSEIF X > 10
  RETURN(3);
ELSE
  RETURN(0);
END

Switch

Testet einen Ausdruck anhand einer Liste von Fällen und gibt den entsprechenden Wert des ersten übereinstimmenden Falls mit einem Standardwert zurück, wenn nichts anderes erfüllt ist.

SWITCH(expression, case1, value1, [case2, ...], [value2, ...], default_value)

Example:

SWITCH( MODBUSR(H, 168, UInt16),
  0, 0,
  0x0002, 1,
  0x0004, 2,
  0x0008, 3,
  0x0010, 4,
  0x0040, 5,
  0x0800, 6,
  NaN)

NaN (not a number) value

NaN can be returned as a value in case real value is not known.

IF Temperature > 250 
  RETURN(NaN);

ISNAN(expression) function
Returns TRUE if expression is not a number.

ISNULL

Returns true if the parameter is NULL, false otherwise. Used for String and Bytearray types. Example: if XML element is not found, returned value ISNULL.

The syntax of the function is:

ISNULL(object)

Sleep

Sleeps the script for number of miliseconds. Use only in very specific cases.

SLEEP(5);

Comments

New line starting with character #

# comment

Numeric literals

Hexadezimalzahlen

Ausdrücke können auch hexadezimale Zahlen interpretieren. Das Präfix 0x ist erforderlich und der Rest unterscheidet nicht zwischen Groß- und Kleinschreibung.

0x0A = 10

0xA0A0   (41120)
0xa0a0   (41120)

Binary numbers

0b1010 = 10

0b10101010   (170)

Mathematische Ausdrücke

+, -, *, /

(20.5 + 9.5) / 2    (15)

Logische Ausdrücke

AND, OR, !, =, !=, >, <

(!IsRaining OR (Wind>30))
MultiValueSwitchState != 2 (Not equal to 2)

Funktionen

LINEAR

Gibt den linear angepassten Wert zurück - lineare Interpolation.

LINEAR(input, value1_input, value1_output, value2_input, value2_output, [type])

Parameter

input… Eingabewert
value1_input… Wert am Eingang an der unteren Grenze
value1_output… Wert am Ausgang an der unteren Grenze
value2_input… Wert am Eingang an der oberen Grenze
value2_output… Wert am Ausgang an der oberen Grenze
[type]… optionaler Parameter. Definiert, was das Ergebnis sein soll, wenn der Eingabewert außerhalb des Bereichs liegt value1_input ↔︎ value2_input:
- ohne Parameter (wie bei Parameter BOUNDS)… Wenn der Eingabewert außerhalb des definierten Bereichs liegt, ist der Ausgabewert einer der Extreme (Minimum oder Maximum)
- INFINITE… Wenn der Eingabewert außerhalb des definierten Bereichs liegt, ist das Ergebnis ein extrapolierter Wert
- STRICT… Wenn der Eingabewert außerhalb des definierten Bereichs liegt, ist der Ausgabewert NaN (keine Zahl)

Examples

Example 1: LINEAR(250,  0,0,  50,500)   (Result is 25°C)

Example 2: LINEAR(Co2,  400,0,  1200,1)
          (If value from Co2 sensor is 400ppm, output for air recovery will be 0%. 
           If Co2 is 1200, output will be 100%. And if e.g. Co2=800, output will be 50%)

Beispiele für verschiedene Attribute [type]:

input = 11
value1_input = 0, value1_output = 400
value2_input = 10, value2_output = 2000
Ergebnis für verschiedene Parameter [type]:
- BOUNDS (Standardwert) = 2000
- INFINITE = 2160
- STRICT = NaN

HYSTERESIS

Hysteresis can be used to filter signals so that the output reacts less rapidly than it otherwise would by taking recent system history into account. For example, a thermostat controlling a heater may switch the heater on when the temperature drops below A, but not turn it off until the temperature rises above B.

Returns 0 or 1.

HYSTERESIS(value, upper_bound, lower_bound, upper_output, lower_output, last_value)

Example: maintain a temperature of 20 °C within 2 ºC hysteresis range. Turn the heater on when the temperature drops to below 18 °C and off when the temperature exceeds 22 °C).

heater := HYSTERESIS(temperature,   22, 18,   0, 1,   heater);

Mathematische Funktionen

MIN

MIN(value1, value2)

Gibt den kleineren der beiden Werte zurück.

MAX

MAX(value1, value)

Gibt den größeren der beiden Werte zurück.

ROUND

ROUND(value1)

Gibt den gerundeten Wert zurück.

Example 1: ROUND(2.01)   (Result is 2)
Example 2: ROUND(2.49)   (Result is 2)
Example 3: ROUND(2.5)   (Result is 3)
Example 4: ROUND(2.99)   (Result is 3)

ABS

The ABS function returns the absolute value (i.e. the modulus) of any supplied number.

ABS(number)

Examples:

ABS(100)  ...   100
ABS(-100)   ...   100

DEWPOINT

DEWPOINT(temperature, relativeHumidity)

Gibt die Taupunkttemperatur bei der aktuellen Temperatur und relativen Luftfeuchtigkeit zurück. Der Taupunkt wird nach folgender Gleichung berechnet: http://bmcnoldy.rsmas.miami.edu/Humidity.html.

Example 1: DEWPOINT(20, 50) (Result is ~9.26)
Example 2: DEWPOINT(0, 100) (Result is 0)

POWER

The POWER function calculates a given number, raised to a supplied power.

POWER(number, power)

Examples:

POWER(2,3) … 2^3 = 8
POWER(10, -3) … 0,001
POWER(25, 0) … 1

MOD

The MOD function returns the remainder of a division between two supplied numbers.

MOD(number, divisor)

Arguments:

number - The number to be divided.
divisor - The value that the number argument is divided by.

Examples:

MOD(6, 4) … 2
MOD(6, 2.5) … 1

CEIL

The CEIL function rounds a supplied number away from zero, to the nearest multiple of a given number.

CEIL(number, significance)

Arguments:

number - The number that is to be rounded.
significance (optional) - The multiple of significance that the supplied number should be rounded to. If the significance is not specified, then it is equal to 1.
(This should generally have the same arithmetic sign (positive or negative) as the supplied number argument)

Examples:

CEIL(22.25,0.1) … 22.3
CEIL(22.25,1) … 23
CEIL(22.25) … 23
CEIL(-22.25,-1) … -23
CEIL(-22.25,1) … -22
CEIL(-22.25) … -22
CEIL(-22.25,-5) … -25

FLOOR

The FLOOR function rounds a supplied number towards zero to the nearest multiple of a specified significance.

FLOOR(number, significance)

Arguments:

number - The number that is to be rounded.
significance (optional) -The multiple of significance that the supplied number is to be rounded to. If the significance is not specified, then it is equal to 1.
(This should generally have the same arithmetic sign (positive or negative) as the supplied number argument)

Examples:

FLOOR(22.25,0.1)… 22.2
FLOOR(22.25,1) … 22
FLOOR(22.25) … 22
FLOOR(-22.25,-1) … -22
FLOOR(-22.25,1) … -23
FLOOR(-22.25) … -23
FLOOR(-22.25,-5) … -20

RAND

The Rand function generates a random real number between 0 and 1.

RAND()

Examples:

RAND()

RANDINT

The RANDINT function generates a random integer between two supplied integers.

RANDINT(bottom, top)

Examples:

RANDINT(1,5)
RANDINT(-2,2)

SIGN

The SIGN function returns the arithmetic sign (+1, -1 or 0) of a supplied number. I.e. if the number is positive, the SIGN function returns +1, if the number is negative, the function returns -1 and if the number is 0 (zero), the function returns 0.

SIGN(number)

Examples:

SIGN(100) … 1
SIGN(0) … 0
SIGN(-100) … -1

SQRT

The SQRT function calculates the positive square root of a supplied number.

SQRT(number)

Examples:

SQRT(25) … 5

LOG

The LOG function calculates the logarithm of a given number, to a supplied base.

LOG(number, base)

Arguments:

number - The positive real number that you want to calculate the logarithm of.
base (optional) - An optional argument that specifies the base to which the logarithm should be calculated.
If the argument is not specified, then the base argument uses the default value 10.

Examples:

LOG(4,0.5) … -2
LOG(100) … 2

LN

The LN function calculates the natural logarithm of a given number.

LN(number)

where the number argument is the positive real number that you want to calculate the natural logarithm of.

Examples:

LN(100) … 4,60517

Bit-Operationen

GETBIT

Returns a value of a bit in the specified position.

GETBIT(number, bit_position)

Arguments:

number - number to extract value of specific bit from
bit_position - position of bit, starting with 0, from right

Examples:

GETBIT(2, 0) → first bit of number 2 (0b0010) is 0
GETBIT(4,2) → third bit of number 4 (0b0100) is 1

GETBITS

Returns value of specified number of bits in the specified position.

GETBITS(number, start_bit, number_of_bits)

Examples:

GETBITS(216, 3, 2) → number 216 = 0b1101 1000; value of 4th bit from the right is 1, 5th bit is 1, therefore result is 0b0011 = 3
GETBITS(0xFF, 0, 4) → number 0xFF = 255 = 0b1111 1111; value of first 4 bits from right is 0b1111 = 0xF = 15

GETBYTE

Returns a value of a byte in the specified number or byte array.

GETBYTE( number, byte_position )
GETBYTE( byte_array, byte_position )

Arguments:

number - number to extract value of specific byte from
byte_position - position of byte, starting from 0, from right

Examples:

GETBYTE(256, 0)  →  0001 0000 0000 →  0
GETBYTE(256, 1)   →  0001 0000 0000  →  1
GETBYTE(259, 0)   →  0001 0000 0011   →  3

GETBYTE(BYTEARRAY(“00 01”), 0) 		(Result is 0)
GETBYTE(BYTEARRAY(“00 02 06”), 2) 		(Result is 6)

SETBYTE

Assigns a new value to the specified byte in the provided number or byte array, and returns assigned value.

SETBYTE( number, byte_position, new_value )
SETBYTE( byte_array, byte_position, new_value )

Examples:

SETBYTE(1, 0, 0)   →   0
SETBYTE(256, 0, 255)   →   511
SETBYTE(256, 1, 1)	  →   256
SETBYTE(259, 1, 2)	  →    515

SETBYTE(BYTEARRAY(“00 01”), 0, 1) 		(Result is 1, byte array is changed to ‘01 01’)

SETBIT

Assigns a new value to the specified bit in the provided number and returns a new number.

SETBIT(number, bit_position, new_value)

Arguments:

number - number to be modified
bit_position - position of bit, starting with 0, from right
new_value - 0 or 1 - value that is going to be set to specified bit

Examples:

SETBIT(1, 1, 1) → 3
SETBIT(3, 1, 1) → 3
SETBIT(4, 2, 0) → 4
SETBIT(12, 1, 0) → 14

SETBITS

Assigns a new value to the specified bits in the provided number and returns a new number.

SETBITS(number, start_bit, number_of_bits, new_value)

Examples:

SETBITS(192, 4, 2, 3) → 240
SETBITS(192, 5, 2, 3) → 224

<< (LEFT BIT SHIFT)

8 << 2   (32)

Excel: BITLSHIFT(number, shift_amount)

>> (RIGHT BIT SHIFT)

32 >> 2   (8)

Excel: BITRSHIFT(number, shift_amount)

& (BITWISE AND)

3 & 1   (1)

Excel: BITAND(number1, number2)

| (BITWISE OR)

2 | 1 (3)

Excel: BITOR(number1, number2)

See the example of bit operations in Google Sheets:
https://docs.google.com/spreadsheets/d/1hF5FMpGMJbgYh-YLwWrq2n186_ATyGyLUb689__IhLY/edit?usp=sharing

Or try interactive tool at http://bitwisecmd.com/

Text, String and Byte array

LENGTH

Return length of an object or number of bytes. Object can be a number, boolean, string or bytearray.

LENGTH( object )

Examples:

LENGTH(“Hello World”)			(Result is 11)
LENGTH(“40”)				(Result is 2)
LENGTH(40)					(Result is 8)
LENGTH(BYTEARRAY(“010203”)	(Result is 3)

BYTEARRAY

Creates a byte array from specified hexadecimal values

BYTEARRAY( bytes )

Examples:

BYTEARRAY(“010203”) 				(Result is byte array 010203)
BYTEARRAY(“aa, be1-1,fe”) 			(Result is byte array aabe11fe)

INDEXOF

Returns index of specified element in string or byte array. -1 if element cannot be found.

INDEXOF( string/byte array, element )

Examples:

INDEXOF("Hello", “H”)					(Result is 0)
INDEXOF("Hello World", “Wor”)				(Result is 6)
INDEXOF("Hello World", “Wor”)				(Result is 6)
INDEXOF("Hello World", “or12”)				(Result is -1)
INDEXOF(BYTEARRAY("ab cd ee ff 01 02"), 2)	(Result is 5)

COPY

Copies specified string or byte array (or part of them)

COPY( string/byte array, startIndex, length)

Examples:

COPY("Hello")					(Result is “Hello”)
COPY("Hello World", 2)				(Result is “llo World”)
COPY("Hello World", 2, 4)				(Result is “llo ”)
COPY(BYTEARRAY("01020304")			(Result is byte array 01020304)
COPY(BYTEARRAY("01020304", 2, 1)		(Result is byte array 03)

REPLACE

Returns a new string or bytearray, in which all occurrences of specified string or byte are replaced with new value.

REPLACE( string/byte array, oldValue, newValue)

Examples:

REPLACE("Hello", “l”, “”)				(Result is “Heo”)
REPLACE("Hello", “lo”, “22”)			(Result is “Hel22”)
REPLACE(BYTEARRAY(“050607"), 5, 9)	(Result is byte array 090607)

ENCODE

Encodes specified string using on of the formats and returns the new string.

ENCODE( string, format )

Supported formats:

XML
Base64 (coming soon)

Examples:

ENCODE("Hello", “xml”)				(Result is “Hello”)
ENCODE("<Hello id=1>", “xml”)			(Result is “&lt;Hello id=1&gt;”)

DECODE

Decodes specified string using on of the formats and returns the new string.

DECODE( string, format )

Supported formats:

XML
Base64 (coming soon)

Examples:

DECODE("Hello", “xml”)				(Result is “Hello”)
DECODE("&lt;Hello id=1&gt;", “xml”)		(Result is “<Hello id=1>”)

Data type conversions

TODOUBLE

Converts string to number. Returns NaN on error.

TODOUBLE( text )

Examples:

TODOUBLE(“232”) ... 232)
TODOUBLE(“-192.332”)  ...  -192.332
TODOUBLE(“some text”)  ...  NaN

TOSTRING

TapHome verwendet intern nur numerische Datentypen, aber in Modbus- und Packet-Parser-Schnittstellen ist es möglich, Dienstattribute zu verwenden, die auch Textwerte unterstützen. Die Funktion gibt den Textwert der Zahl gemäß dem durch den zweiten Parameter angegebenen Format zurück.

TOSTRING(number, format_specifier)

Examples:

TOSTRING(192, “X”)  …  Result = “C0”
TOSTRING(192, “X4”)  …  Result = “00C0”
TOSTRING(192, “F4”)  …  Result = “123.3400”
TOSTRING(192, “F0”)  …  Result = “123”

Returns a string value of the specified byte array according to the specified encoding. Encoding is optional (iso-8859-1 is used by default).

TOSTRING( bytearray, encoding)

Examples:

TOSTRING(BYTEARRAY("48656c6c6f"))			(Result is “Hello”)
TOSTRING(BYTEARRAY(\"48656c6c6f\"), “iso-8859-1”)	(Result is “Hello”)

TOBCD

Converts the provided number to the binary-coded decimal (BCD) format. The scheme of encoding is BCD-8421.

TOBCD(number)

Examples:

TOBCD(1)  ...  1
TOBCD(9)  ...  9
TOBCD(10)  ...  16

FROMBCD

Decodes the provided number, that is encoded in binary-coded decimal (BCD) format. The scheme of encoding is BCD-8421.

FROMBCD(number)

Examples:

FROMBCD(16)  ...  10
FROMBCD(32)  ...  20

TOBYTEARRAY

Converts string to byte array according to the specified encoding. Encoding is optional (iso-8859-1 is used by default).

TOBYTEARRAY( string, encoding )

Examples:

TOBYTEARRAY("Hello")			(Result is byte array 48656c6c6f)

Parsing functions

PARSETEXT

Returns part of input text, based on left and right search patterns

PARSETEXT( input, left_pattern, right_pattern)

Examples:

PARSETEXT(“Lorem ipsum dolor sit amet”, “ipsum”, “amet”) (Result is “dolor sit”)
PARSETEXT(“<temp>12.2</temp>”, “<temp>”, “</temp”) (Result is 12.2)
PARSETEXT(“<temp>12.2</temp>”, “<temp>”) (Result is 12.2)
PARSETEXT(“status:ok,error:none”, “status:”) (Result is “ok”)
PARSETEXT(“Lorem ipsum dolor sit amet”, “ipsum”) (Result is “dolor”)
PARSETEXT(“Lorem ipsum dolor sit amet”, “ipsum…sit”) (Result is “amet”)
PARSETEXT(“Lorem ipsum dolor sit amet consectetur adipiscing”, “ipsum…sit”, “adipiscing”) (Result is “amet consectetur”)

PARSEJSON

Returns value of element from json formatted string. Element is specified with json path.

PARSEJSON( json_string, json_path, ignore_error)

Examples:

With json = { "firstName": "John",
  "lastName" : "doe",
  "age" : 26,
  "address"  : {
    "streetAddress": "naist street",
    "city"         : "Nara",
    "postalCode"   : "630-0192"
  }
}

PARSEJSON(json, “firstName”)			(Result is “John”)
PARSEJSON(json, “address.city”)		(Result is “Nara”)
PARSEJSON(json, “address.country”)		(error)
PARSEJSON(json, “address.country”, 0)		(error)
PARSEJSON(json, “address.city”, 1)		(Result is null)

PARSEXML

Returns value of element from xml string. Element is specified with xml path.

PARSEXML( xml_string, xml_path)

Examples:

With xml= <?xml version="1.0"?>
<catalog>
	<book id="bk101">
		<author>Gambardella, Matthew</author>
		<title>XML Developer's Guide</title>
		<genre>Computer</genre>
		<price>44.95</price>
		<publish_date>2000-10-01</publish_date>
		<description>An in-depth look at creating...</description>
	</book>
	<book id="bk102">
		<author>Ralls, Kim</author>
		<title>Midnight Rain</title>
		<genre>Fantasy</genre>
		<price>5.95</price>
		<publish_date>2000-12-16</publish_date>
		<description>A former architect battles…</description>
	</book>
</catalog>

PARSEXML(xml, “//catalog/book[1]/price”) (Result is 44.95)
PARSEXML(xml, “//book[2]/title”) (Result is “Midnight Rain”)
PARSEXML(xml, “//book[1]/@id”) (Result is “bk101”)
PARSEXML(xml, “//catalog/magazine[1]/price”) (Result is null)

If xml contains namespaces, you have to fully specify element names with namespace, eg. PARSEXML(xml, "//DIDL-Lite:container[dc:title='My Playlist’']/DIDL-Lite:res");

Packet parser

SENDHTTPREQUEST

Sends http request with specified parameters, waits for response and returns response as JSON string with values as Content, Headers, Http result code. Function is supported only in Packet parser scripts with Http protocol.

SENDHTTPREQUEST( path, method, body, header1, header2… )

Examples:

SENDHTTPREQUEST("/getValue")		Result is:
{
  "Headers": [
    {
      "Key": "Content-Type", “Value": [“application/json"]
    },
    {
      "Key": "Content-Length", “Value": ["1007"]
    },
  ],
  "Content": "{\"value\":31}”,
  "ReasonPhrase": "OK",
  "StatusCode": 200,
  "IsSuccess": true
}

SENDHTTPREQUEST("/doSomething", “POST”, “someData”, “header1:value1”, “header2:value2”, “header3:value3”)

SENDDATA

Sends specified data (string or bytearray) using tcp or udp protocol. If data is a string object, it’s implicitly converted to bytes using iso-8859-1 encoding. Function is supported only in Packet parser scripts with TCP or UDP protocol. Received bytes can be processed in Listener script.

SENDDATA( string/bytearray )

Examples:

SENDATA(BYTEARRAY(“0a dd ef a2”)
SENDATA(“{\”value\”:212}”)

FTPDOWNLOAD

Returns file data (as byte array) from ftp server. Function is supported only in Packet parser scripts with FTP protocol.

FTPDOWNLOAD( pathToFile )

Examples:

FTPDOWNLOAD(“/path/to/file”) 		(Result is byte array)

FTPUPLOAD

Uploads data (byte array or string) to a file to ftp server.

FTPUPLOAD( pathToFile, data, mode )

Examples:

FTPUPLOAD(“/path/to/file”, “some data”, “write”)
FTPUPLOAD(“/path/to/file”, BYTEARRAY(“a7 ff e2”), “append”)

COMPLETESERVICEATTRIBUTE

Function is used in listener scripts in packet parser with TCP/UDP protocol, to notify completion of service attribute value request. Eg. you create a request in service attribute script using the SENDDATA function and after receiving the data in listener script, you complete the service attribute read.

COMPLETESERVICEATTRIBUTE( attributeName, value, error )

Examples:

COMPLETESERVICEATTRIBUTE(“Uptime”, “2d:21h:43m”)
COMPLETESERVICEATTRIBUTE(“Status”, “”, “Device is offline”)

COMPLETESERVICEACTION

Function is used in listener scripts in packet parser with TCP/UDP protocol, to notify completion of service action request. Eg. you create a request in service action script using the SENDDATA function and after receiving the data in listener script, you complete the service action.

COMPLETESERVICEACTION( actionName, result )

Examples:

COMPLETESERVICEACTION(“Reboot”, “Rebooted successfully”)
COMPLETESERVICEACTION(“Enable cloud”, “Device is offline”)

Modbus

Folgen Sie diesem Link, um weitere Informationen zur Modbus-Konfiguration zu erhalten.