Active Systems: 2497
Active Wireless Remotes: 4015
Total Active IOT Devices: 6512
 

ITU G2 Expressions

The ITU_G2 introduces a powerful system of expressions to go along with the flexibility of the new log map. Commonly used expressions will tend to be fairly simple, but to meet specific requirements some quite complex expressions can be devised.

Expressions are used to define the ^HIMG, ^HLOP, ^HSCO, ^HDCR, ^HDYR, and relay control settings, but, in addition, a set of user expressions can be defined. User expressions can be used to define terms that can then be used in other expressions. This allows complex expressions to be created without them having to become incomprehensible.

The syntax of an expression can be defined as follows:

expression ::= expression_term { boolean_operator expression_term }
expression_term ::= data_identifier_term | [ ! ] defined_term
data_identifier_term ::= log_field_number [ bit_mask ] [ ! ] comparison_operator
log_field_number ::= 0 .. 127
bit_mask ::= [ bit_range { , bit_range } ]
bit_range ::= bit_number [ - bit_number ]
bit_number ::= 0 .. 22
comparison_operator ::= L | H | C
defined_term ::= expression_name | forward_referenced_expression | function_term
expression_name ::= standard_expression_name | user_expression_name
standard_expression_name ::= nameable_expression_name | fixed_expression_name
nameable_expression_name ::= nameable_expression_prefix expression_number
nameable_expression_prefix ::= ROFF | RON | X
expression_number ::= 1 .. 8
fixed_expression_name ::= static_system_term | dynamic_system_term | system_expression_name
static_system_term ::= FALSE | TRUE | TOD1 | TOD2 | LIGHT | TOY1 | TOY2 | SUN | MON | TUE | WED | THU | FRI | SAT | NI | RSP | PDP | TCP | ICT1 | ICT2 | EXP
dynamic_system_term ::= RST | TEST | RTEST | T_5 | T_10 | T_15 | T_30 | T1 | T2 | T3 | T4 | T5 | T10 | T15 | T30 | T60 | TX9 | SCT | ROT1 | ROT2 | ROT3 | ROT4 | ROT5 | ROT6 | ROT7 | ROT8 | NIE | RSPE | SUNRISE | SUNSET | TIME1 | TIME2
system_expression_name ::= SCO | LOP | IMG | DCR | DYR
forward_referenced_expression ::= { nameable_expression_name : user_expression_name }
user_expression_name ::= letter { letter | digit }
letter ::= A .. Z | a .. z | _
digit ::= 0 .. 9
function_term ::= poly_function_term | path_function_term
poly_function_term ::= INPOLYpolygon_nunber ( log_field_number , log_field_number )
polygon_number ::= 1 .. 2
path_function_term ::= ONPATHpath_number ( log_field_number , log_field_number , path_range_distance )
path_number ::= 1 .. 8
path_range_distance ::= 5 .. 250
boolean_operator ::= + | .

Data Terms

A data_identifier_term contains a reference to one of the 128 value fields in the log record (the log_field_number). If an optionally bit_mask is specified then the comparisons applied to this term will be based on bit-wise Boolean logic, otherwise numeric comparisons will be used. When a bit_mask is used only those bits inclued in the mask are used in the comparison.

ComparisonNumeric valueBit field
L<Low thresholdAll bits 0
!L>Low thresholdOne or more 1 bits
H>High thresholdAll bits 1
!H<High thresholdOne or more 0 bits
C>Change thresholdAny bits different
!C<Change thresholdAll bits the same

Change comparisons are based on the absolute difference from the matching log field in the last log record. It is therefore necessary to write log records at suitable times to have values to compare against. If a change comparison is used to trigger a call then it is generally necessary to write a log record at the time of the call so that the comparison does not remain true following the call.

Level comparisons are based on the current level of the input. Since a level comparison can remain true for some time it is generally necessary to combine level comparison terms with time based terms.

Thresholds are defined using the ^HATH command and are associated with a log record entry using the ^HLM command.

Standard Terms

TermSet TrueTypeMin. Code Version
FALSENeverStatic0.01.00
TRUEAlwaysStatic0.01.00
TOD1When the time of day is within defined rangeStatic0.02.02
TOD2When the time of day is within defined rangeStatic0.02.02
LIGHTWhen the time of day is between sunrise and sunsetStatic0.03.00
TOY1When the time of year is within defined rangeStatic0.02.02
TOY2When the time of year is within defined rangeStatic0.02.02
SUNWhen it's a SundayStatic0.02.02
MONWhen it's a MondayStatic0.02.02
TUEWhen it's a TuesdayStatic0.02.02
WEDWhen it's a WednesdayStatic0.02.02
THUWhen it's a ThursdayStatic0.02.02
FRIWhen it's a FridayStatic0.02.02
SATWhen it's a SaturdayStatic0.02.02
NIWhen a new image becomes availableStatic0.03.00
RSPWhen a response to a LRR command is receivedStatic0.04.02
PDPWhen a PDP session is establishedStatic0.06.12
TCPWhen a TCP connection is establishedStatic0.03.04
ICT1ICT1 minutes after a callStatic0.01.00
ICT2ICT2 minutes after a callStatic0.01.00
EXPWhen the camera is taking a photoStatic0.05.00
RSTAt resetDynamic0.01.00
TESTWhen test button pressedDynamic0.01.00
RTESTWhen an LRR has its test button pressedDynamic0.04.02
T_5Every 5 secondsDynamic0.01.07
T_10Every 10 secondsDynamic0.01.07
T_15Every 15 secondsDynamic0.01.07
T_30Every 30 secondsDynamic0.01.07
T1Every minuteDynamic0.01.00
T2Every 2 minutesDynamic0.06.19
T3Every 3 minutesDynamic0.06.19
T4Every 4 minutesDynamic0.06.19
T5Every 5 minutesDynamic0.01.00
T10Every 10 minutesDynamic0.01.00
T15Every 15 minutesDynamic0.01.00
T30Every 30 minutesDynamic0.01.00
T60Every hourDynamic0.01.00
TX9Every minute ending in 9Dynamic0.06.19
SCTAt a scheduled call timeDynamic0.01.00
ROTnWhen the relay n timer expires (n=1-2)Dynamic0.01.13
ROTnWhen the relay n timer expires (n=3-4)Dynamic0.03.00
ROTnWhen the relay n timer expires (n=5-8)Dynamic0.05.01
NIEWhen a new image becomes availableDynamic0.04.02
RSPEWhen a response to a LRR command is receivedDynamic0.04.02
SUNRISEWhen the time matches the current sunrise timeDynamic0.03.03
SUNSETWhen the time matches the current sunset timeDynamic0.03.03
TIMEnWhen the TIMEn setting matches the current timeDynamic0.06.11
SCOWhen the SCO expression evalutes trueExpression0.01.00
LOPWhen the LOP expression evalutes trueExpression0.01.00
IMGWhen the IMG expression evaluates trueExpression0.03.00
DCRnWhen the DCR expression evalutes trueExpression0.06.11
DYRnWhen the DYR expression evalutes trueExpression0.06.14
ROFFnWhen the ROFFn expression evalutes true (n=1-2)Expression0.01.13
ROFFnWhen the ROFFn expression evalutes true (n=3-4)Expression0.03.00
ROFFnWhen the ROFFn expression evalutes true (n=5-8)Expression0.05.01
RONnWhen the RONn expression evalutes true (n=1-2)Expression0.01.13
RONnWhen the RONn expression evalutes true (n=3-4)Expression0.03.00
RONnWhen the RONn expression evalutes true (n=5-8)Expression0.05.01
XnWhen the Xn expression evalutes trueExpression0.01.00
INPOLYn()When the specified point is within the polygon (n=1-2)Function0.05.03
ONPATHn()When the point is within the specified distance of the path (n=1-8)Function0.06.26

All the, Txx, time expressions are set to true when the real time clock minute reaches a suitable multiple. For example, T5 is set when the real time clock minute field is incremented to 0, 5, 10, 15, etc. The TX9 expression is a special case because it is set every ten minutes when the real time clock is incremented to a minute that ends in 9. That is 9, 19, 29, 39, 49, and 59.

All the, T_xx, time expressions are set to true when the real time clock second reaches a suitable multiple. For example, T_15 is set when the real time clock second field is incremented to 0, 15, 30, or 45.

The ICT timers count down from the time DTR was last de-asserted so the terms will be set true again after their set time intervals regardless of the success or otherwise of the previous call. These terms are reset when the SCO expression is next evaluated true.

The SCT terms is set when the real time clock increments to match any of the defined scheduled call times.

The PDP term is set when a PDP context is established and cleared when the context is closed. This allows expressions to be created that can, for example, cause a new PDP context to be established based on the PDP context status.

The TCP term is set when a TCP connection is established and cleared when the connection is closed. This allows expressions to be created that can, for example, cause a new connection to be established or take alternative relay control action based on the TCP connection status.

The IMG, SCO, LOP, ROFFn, and RONn terms are set when their expressions evaluate to true. These are special purpose expressions but can be defined and used just like a user expressions with the exceptions that they cannot be named and that they have their own effects.

The ROTn terms are set when their respective relay operate timers expire. These timers are triggered by the RONn expressions (or a ^HSOn=1 command) and can be used as general purpose timers so long as the relay operation, if there is one, is not significant.

The TODn and TOYn terms are true whenever the time or date is within the range defined by the corresponding ^HTOD or ^HTOY command.

The day of week terms, SUN through SAT, are true on there corresponding day of the week. The day of week is calculated by the ITU based on the year, month, and day set in its real time clock.

The LIGHT term is set when the time of day is within the calculated sunrise to sunset time range. This time range is calculated based on the date and location of the ITU.

The SUNRISE and SUNSET terms are set when the time of day matches the calculated sunrise or sunset times respectively for the current day.

The EXP term is set shortly before the ITU issues the camera command to capture a photo and remains true until the capture is completed. This will go false before the image is retrieved from the camera so if, for example, this term is used to operate a relay and infra-red flood light then the operate time can be much shorter.

The NI (New Image) and NIE (New Image Event) terms are set when an image capture sequence is successfully completed. An image capture sequence will be started when the IMG expression evaluated to true and the NI term will indicate completion. The NI term is a static term whereas the NIE term is a dynamic term. The NI term is reset when an image file is closed.

The RSP and RSPE terms are set when a response to a LRR command is received. The RSP term is a ststic term whereas the RSPE term is dynamic. The RSP term is reset when a ^HSPI command is issued.

The RTEST term is set when an LRR, that's in the ITU's log may, has its test button pressed.

Static and Dynamic Terms

By the nature of the conditions to which they relate some terms remain true for a period of time. Take for example the FRI term; this remains true for a full 24 hours. We refer to these as static terms. Static terms all have some event that sets them true and another event that sets them false again. Taking our FRI example again; this is set when the clock ticks over midnight changing from Thursday to Friday and is reset by the next midnight rollover.

Other terms relate to events that are transient in nature such as the pressing of the test button setting the TEST term. We refer to these as dynamic terms. Dynamic terms are reset after being used to evaluate all the expressions.

Care needs to be taken with the type of terms used in expressions. A static term will remain true for a period of time so can result in a rapidly repeated action for the duration of the term being true. On the other hand, the ANDed combination of two dynamic terms will very rarely ever evaluate true. Typical usage is likely to have a dynamic term ANDed with one or more static terms.

Expressions may end up as either static or dynamic depending on the nature of the terms used to evaluate them. When evaluating an expression the ITU will seek to find a product term that evaluates true based on only static terms. Such a term we make the resulting expression evaluation static. If the expression can only be evaluated true based on a dynamic term then the resulting expression evaluation will by dynamic.

Function Terms

The function terms INPOLY1() and INPOLY2() take two parameters in the form of log map references. These two log entries are used to define a point. The INPOLY functions test this point to see if it is within the polygon specified by the matching ^HPOLY command.

The function terms ONPATH1() through to ONPATH8() take three parameters. The first two are in the form of log map references and the third is a distance in metres. The first two parameters must define the latitude and longitude, in that order, of a location. The latitude is used to allow calculation of the distance to the path in metres. The ONPATH functions calculate the distance to the nearest point on the corresponding path and compare this to the distance parameter.

User Expression Terms

Eight user expressions, X1 to X8, can be defined. These provide a way of creating sub-expressions that can then be used in other expressions. This allows for complex expressions to be build from simple, more easily understood, sub-expressions.

Naming of user expressions is recommended to enhance comprehension. User expression can be assigned names of up to seven characters in length. Letters, digits and the underscore character ('_') are permitted in expression names although they may not start with a digit. Letters may be entered in either upper or lower case but are all converted to upper case. Names may not confict with standard expression names. If an expression has a name and the expression is redefined, the name will be retained so long as no new name is specified. An empty name string ("") may be specified if the user wishes to delete an existing name without defining a new name.

Names of expressions are stored with the expression that is so named. References to the named expression are stored numerically. This means that should a name be changed then all references to it will also change.

The relay control expressions, ROFF1 to ROFF8 and RON1 to RON8, can also be used as user expressions but with the addition of state memory, timers, and the ability to control excitation outputs.

Some Rules Regarding Expressions

Circular references are not permitted. This includes circular references that go via several different expressions.

Only eight terms are permitted in any one expression. If more are needed then user expressions should be used to define suitable sub-expressions.

Named expressions may only be referred to by their names if the names are already defined. If it is necessary to reference a user expression before it is named then the Xn syntax can be used. Optionally, to help clarity of the expressions, the forward reference syntax, {Xn:name}, may be used. When it is, only the Xn part is used by the ITU; the name is documentative only.

Examples

AT^HX1"COLD"=23L+24L+25L+26L+27L+28L+29L+30L
AT^HX4"IDLE"=10[0-8]!L+15[1]H+17[1]H
AT^HLOP=COLD.T1+!IDLE.45[3-4]!H+X7

The user expression X1 is assigned the name COLD and is true if any one of the data values 23 to 30 are below their respective thresholds. Typically a suitable threshold set would be defined and applied to all these data values but this doesn't have to be the case.

The user expression X4 looks more complicated but just states that if any one of 11 different bits is true then it will be true. Typically such an expression would be used to look at digital inputs (which are likely to be bit mapped). It is possible to look at other types of inputs this way but it would generally not be a good idea.

The LOP expression is really just a made up example to show what can be done. The five terms of this expression form three products terms: COLD.T1, !IDLE.45[3-4]!H, and X7. Any one product term true will result in generation of a log record. The first product term will cause one minute logging whenever any of the eight temperature inputs referenced in the X1 expression is below its low threshold. The second product term requires that the IDLE expression is false and data value 45 has a zero bit in position 3 or 4. The final term we know nothing about because the X7 term is not defined here. Note that when listing user expressions, any expression that is defined as FALSE will not be listed. This is how unused expressions can be cleared.