Utility Entity Functions
Sep 28 2022 at 12:00 AM
- And
- Any
- Default If Null
- Is Equal To
- Is Greater Than Or Equal To
- Is Greater Than
- Hold Value
- If True
- Is Null
- Last Not Null
- Not
- Is Not Equal To
- Is Smaller Than Or Equal To
- Is Smaller Than
- Value Changed
- When Sequence Completes
- Between Utility Function
And
Function Description:
This function is used when two or more conditions need to be met simultaneously for a trigger or function to fire. If used on its own it will output a Boolean, True if all conditions are met, or False if one or more conditions are not met. You can use the And function to add multiple conditions to a function or trigger.
Function Structure:
![](/assets/images/commander/functions/and.png)
Figure 1 - And
Inputs Required:
- Condition - A logical statement of data type boolean.
Once a condition has been added the option to add more conditions becomes available. |
Output Expected:
- Boolean - The function will return a boolean value. True if all conditions are true, and False if any of the conditions are false.
Use Case Example(s):
Example | Condition 1 Output | Condition 2 Output | Condition 3 Output | Condition 4 Output | AND Output |
---|---|---|---|---|---|
1 | True | True | TRUE | ||
2 | True | False | FALSE | ||
3 | True | True | False | FALSE | |
4 | True | True | True | True | TRUE |
Use Case Scenario(s):
1. If your engine speed is online and if RPMs (engine speed) is greater than 0; output that the engine is running, otherwise output “Engine is at rest” or is “Offline”.
2. If the air conditioner is off and the room temperature is above 30°C, signal that the aircon should turn on.
3. If it is after hours, the door is open, and movement is detected, then an alarm “INTRUDER ALERT!” should be raised.
Any
Function Description:
Any operates as an OR function. It determines if one or more of the conditions are true. Only one condition needs to be true for the function result to be true.
Function Structure:
![](/assets/images/commander/functions/any.png)
Figure 2 - Any
Inputs Required:
- Condition - A logical statement of data type boolean.
Once a condition has been added the option to add more conditions becomes available. |
Output Expected:
- Boolean - The function will return a boolean value. True if any of the conditions are true, and False if none of the conditions are true.
Use Case Example(s):
Example | Condition 1 Output | Condition 2 Output | Condition 3 Output | Condition 4 Output | ANY Output |
---|---|---|---|---|---|
1 | True | True | TRUE | ||
2 | True | False | TRUE | ||
3 | False | False | False | FALSE | |
4 | True | False | True | True | TRUE |
Use Case Scenario(s):
1. If any of the generators are offline, raise an alarm.
2. If any of the doors are opened after hours, when site is armed, trigger an alarm.
Default If Null
Function Description:
This function can be used to provide an endpoint with an alternate output message or value if said endpoint is null.
Function Structure:
![](/assets/images/commander/functions/default_if_null.png)
Figure 3 - Default If Null
Inputs Required:
- Value - This is where you will put the endpoint being assessed for “if null”.
- Default Value - The value which you want your output to be if the endpoint is null.
Output Expected:
- Value - The output would either be n/a (if the endpoint is live) or the specified default value (if the endpoint is null).
Use Case Example(s):
Example | Value | Default Value | Default If Null Output |
---|---|---|---|
1 | null | Endpoint is null | Endpoint is null |
2 | True | Endpoint is null | N/A |
3 | 29.7 | Temperature sensor faulty | N/A |
4 | null | Temperature sensor faulty | Temperature sensor faulty |
Use Case Scenario(s):
1. If room temperature sensor is sending a null value, display a message that the “Temperature sensor is faulty”.
2. If the readings from a generator are sending null, output a message that states that “Please check that the generator is installed correctly and online”
Is Equal To
Function Description:
Compares two values and determines if they are equal. For the function to be triggered the values being compared must be of the same data type. The value returned is always a boolean (true/false).
Function Structure:
![](/assets/images/commander/functions/is_equal_to.png)
Figure 4 - Is Equal To
Inputs Required:
- Value 1 - A datapoint of any data type to be compared if it is equal to input Value 2. This can be a boolean, a string, a number, etc.
- Value 2 - A datapoint of any data type to be compared with input Value 1. This should be the same data type as Value 1.
Output Expected:
- Boolean - Is Equal to Value function returns a boolean (true/false) when the received values have been compared.
Use Case Example(s):
Example | Value 1 | Value 2 | Is Equal To Output |
---|---|---|---|
1 | 31 | 52 | FALSE |
2 | “111” | 111 | FALSE |
3 | abc | abc | TRUE |
4 | 0.6 | 0.6 | TRUE |
5 | data | data | TRUE |
Use Case Scenario(s):
1. If generator fuel level is 0%, raise an alarm.
2. If the current date is two weeks before the service deadline for a car, send an SMS reminder to book a service.
Is Greater Than Or Equal To
Function Description:
This function determines if the first value it receives is greater than or equal to the second value. The values being compared must be of the same type and the value returned is always a boolean (true/false).
Function Structure:
![](/assets/images/commander/functions/is_greater_than_or_equal_to.png)
Figure 5 - Is Greater Than Or Equal To
Inputs Required:
- Value 1 - A datapoint of any data type to be compared if it is greater than or equal to input Value 2. This can be a boolean, a string, a number, etc.
- Value 2 - A datapoint of any data type to be compared with input Value 1. This should be the same data type as Value 1.
Output Expected:
- Boolean - Is Greater Than Or Equal To function returns a boolean (true/false) value when the received values have been compared.
Use Case Example(s):
Example | Value 1 | Value 2 | Is Greater Than Or Equal To Output |
---|---|---|---|
1 | 23 | 12 | TRUE |
2 | 9.0 | 9.0 | TRUE |
3 | “abc” | “def” | FALSE |
4 | 2018/01/01 | 2019/01/01 | FALSE |
5 | 7 | 7 | TRUE |
Use Case Scenario(s):
1. If a temperature is greater than or equal to the setpoint/threshold, raise an alarm.
2. If an asset has been in an area for longer than or equal to a specified time, raise an alarm.
Is Greater Than
Function Description:
This function determines if the first value it receives is greater than the second value. The function returns as true if the first value is greater, and as false if the first value is smaller than the second value.
Function Structure:
![](/assets/images/commander/functions/is_greater_than.png)
Figure 6 - Is Greater Than
Inputs Required:
- Value 1 - A datapoint of any data type to be compared if it is greater than input Value 2. This can be a boolean, a string, a number, etc.
- Value 2 - A datapoint of any data type to be compared with input Value 1. This should be the same data type as Value 1.
Output Expected:
- Boolean - Is Greater Than function returns a boolean (true/false) value when the received values have been compared.
Use Case Example(s):
Example | Value 1 | Value 2 | Is Greater Than Output |
---|---|---|---|
1 | 23 | 11 | TRUE |
2 | 9.0 | 3.0 | TRUE |
3 | “abc” | “def” | FALSE |
4 | 2018/01/01 | 2019/01/01 | FALSE |
5 | 7 | 7 | FALSE |
Use Case Scenario(s):
1. If a temperature is greater than the setpoint, raise an alarm.
2. If the fridge door has been left open for longer than 3 minutes, raise an alarm.
Hold Value
Function Description:
This function holds a value of an endpoint for the specified duration of the third parameter (Timespan) when the second parameter (Boolean - Should Hold) is true.
If the Should Hold condition changes to false before the timespan timer has ended, the function will still hold the endpoint value until the time is up, and then display the true endpoint value.
If the Should Hold condition is still true once the timespan timer has ended, the timer will start again and hold the latest value of the endpoint.
Function Structure:
![](/assets/images/commander/functions/hold_value.png)
Figure 7 - Hold Value
Inputs Required:
- Value - This is the endpoint value you want the function to hold.
- Should Hold - This is the condition (of data type boolean) for when the function should be held. Only if the condition is true will the function begin holding the value for the specified timespan.
- Timespan - This is how long the function should hold the endpoint value for (HH:MM:SS).
Output Expected:
- Output - The held value of the endpoint (if “Should Hold” is true), otherwise the output will be the live value of the endpoint (Value).
Use Case Example(s):
EndpointDatetime | EndpointValue | ShouldHold | Value Hold Output | Timespan | WHY |
---|---|---|---|---|---|
2018/01/01 10:00:00 | 2 | false | 2 | ShouldHold is false, handle the endpoint value as normal | |
2018/01/01 10:00:15 | 4 | true | 4 | 0:00 (starts) | Condition is true, timer starts |
2018/01/01 10:00:30 | 3 | false | 4 | 0:15 | Timer has not elapsed, hold value |
2018/01/01 10:00:45 | 2 | false | 4 | 0:30 | Timer has not elapsed, hold value |
2018/01/01 10:01:00 | 1 | false | 4 | 0:45 | Timer has elapsed, hold is no longer valid |
2018/01/01 10:01:15 | 3 | false | 3 | ShouldHold is false, handle the endpoint value as normal | |
2018/01/01 10:01:30 | 0 | false | 0 | ShouldHold is false, handle the endpoint value as normal |
Use Case Scenario(s):
1. In a solar power system, if the batteries are nearing the set low level, hold the value until reset.
2. If a vehicle is over a speed-limit, hold the value for a specified time (ie. 15 minutes if 60 km above speed-limit). The figure Hold Value Function 2 below is for further clarity on the build.
![](/assets/images/commander/functions/hold_value_scenario.png)
Figure 8 - Hold Value Function Scenario 2
If True
Function Description:
The function assesses the condition given and gives the user the ability to output certain outputs based on whether the condition input is true or false.
Function Structure:
![](/assets/images/commander/functions/if_true.png)
Figure 9 - If True
Inputs Required:
- Condition - A condition of data type boolean.
- If true - A value of any data type that the function should output if the condition provided is true.
- If false - A value of any data type that the function should output if the condition provided is true.
Output Expected:
- Boolean - If True function will return one of the options provided for the If true or the If false inputs, depending on whether the condition is met or not.
Use Case Example(s):
Example | Condition | If true | If false | If True Output |
---|---|---|---|---|
1 | Door status = true | “Door is open” | “Door is closed” | “Door is open” |
2 | 12/2 = 3 | “Yes” | “Incorrect” | “Incorrect” |
3 | GeneratorOnline = true AND EngineSpeed > 0 | “Generator Running” | “Generator at rest” | “Generator Running” |
The figure below displays Example 1 in build form.
![](/assets/images/commander/functions/if_true_example.png)
Figure 10 - If True Example
Use Case Scenario(s):
1. In the event of load shedding, signal to switch on the generator after 2 minutes of the power being cut, otherwise ensure the generator is at rest.
2. If the intruder alarm is in active state, update the Digital Overlay with a red border, otherwise reset the Digital Overlay to a green border.
Is Null
Function Description:
When the function receives a null value from a gateway or device, a Boolean output is returned as true. If the value is anything other than null, it will return a false output.
Function Structure:
![](/assets/images/commander/functions/is_null.png)
Figure 11 - Is Null
Inputs Required:
- Value - An endpoint or function of any data type outputting a value that is required to be checked if ever null.
Output Expected:
- Boolean - Is Null function returns a boolean (true/false) value depending on whether the value of the entity being checked is null (true) or not (false).
Use Case Example(s):
Example | Value | Is Null Output |
---|---|---|
1 | Null | TRUE |
2 | 10 | FALSE |
3 | 38 | FALSE |
4 | Null | TRUE |
5 | 2 | FALSE |
Use Case Scenario(s):
1. Checking live endpoint data from a gateway to determine if the gateway is online or not.
2. If a generator has been sending nulls (it could be because the Raptor has been disconnected from the controller or the generator battery has died, etc) for more than a day, send an alarm “Technician Required On Site”
Last Not Null
Function Description:
This function will return a boolean value if the information from the entity being assessed is not null.
This function is opposite to the “Is Null” function. An outcome of True for the “Is Null” function would output a False for the “Last Not Null” function. |
Function Structure:
![](/assets/images/commander/functions/last_not_null.png)
Figure 12 - Last Not Null
Inputs Required:
- Value - An endpoint or function of any datatype outputting a value that is required to be checked if ever null.
Output Expected:
- Boolean - Last Not Null function returns a boolean (true/false) value depending on whether the value of the entity being checked is not null (true) or is null (false).
Use Case Example(s):
Example | Value | Last Not Null Output |
---|---|---|
1 | Null | FALSE |
2 | 10 | TRUE |
3 | Null | FALSE |
4 | Null | FALSE |
5 | 52 | TRUE |
Use Case Scenario(s):
1. Checking whether a device is online by receiving a true because the value is not null.
2. Checking the vital organs’ functionality of a patient on a life support system.
Not
Function Description:
This function is used to indicate if an endpoint value is not another endpoint’s value. It then returns a boolean (true/false) value.
This function will not output anything as the NOT function is supposed to be used within other functions. If you wish for it to return a value, you will need to include a triggering function, such as an if true statement. |
Function Structure:
![](/assets/images/commander/functions/not.png)
Figure 13 - Not
Inputs Required:
Value - An entity value that something is being compared against to not match.
Output Expected:
Output - The output would be that of the function using the NOT entity function in conjunction with other entity functions, where the NOT portion would allow a user to compare against a specific entity for a mismatch.
Use Case Example(s):
The figure below displays how the NOT function is used in conjunction with another function. This example is to check if your room temperature is not at a threshhold, then send an SMS.
![](/assets/images/commander/functions/not_trigger.png)
Figure 14 - Not Use Case Example
Use Case Scenario(s):
1. If an average speed is not the same as projected, it should return as true for monitoring to be executed by the logistics team.
2. If a current temperature is not equal to the projected temperature it should return as true for monitoring to be executed by the facilities team.
3. If you are allergic to cucumbers, and you want to make sure that cucumbers are not on your grocery list.
Is Not Equal To
Function Description:
Compares two values and determines if they are not equal.
Function Structure:
![](/assets/images/commander/functions/is_not_equal_to.png)
Figure 15 - Is Not Equal To
Inputs Required:
- Value 1 - A datapoint of any data type to be compared if it is not equal to input Value 2. This can be a boolean, a string, a number, etc.
- Value 2 - A datapoint of any data type to be compared with input Value 1. This should be the same data type as Value 1.
Output Expected:
- Boolean - Is Not Equal To function returns a boolean (true/false) value. It returns a true if the two values do not equal one another, and false if they are equal.
Use Case Example(s):
Example | Value 1 | Value 2 | Is Not Equal To Output |
---|---|---|---|
1 | 12 | 20 | TRUE |
2 | "111" | 111 | TRUE |
3 | "abc" | "abc" | FALSE |
4 | True | False | TRUE |
5 | 50 | 50 | FALSE |
Use Case Scenario(s):
1. If the freezer door is not closed, notify the site manager.
2. If the speed is not equal to 0 (i.e. Moving), notify the site manager.
Is Smaller Than Or Equal To
Function Description:
Determines if the first value it receives is smaller than or equal to the second value. The function returns as true if the first value is smaller or equal to the second value.
This function can be used to compare DateTimes as well (thus determining whether something is newer or older than a reference point). |
Function Structure:
![](/assets/images/commander/functions/is_smaller_than_or_equal_to.png)
Figure 16 - Is Smaller Than Or Equal To
Inputs Required:
- Value 1 - A datapoint of any data type to be compared if it is smaller than or equal to the input Value 2. This can be a boolean, a string, a number, etc.
- Value 2 - A datapoint of any data type to be compared with input Value 1. This should be the same data type as Value 1.
Output Expected:
- Boolean - Is Smaller Than Or Equal To function returns a boolean (true/false) value. True is returned if value 1 is smaller than or equal to value 2, and a false if not.
Use Case Example(s):
Example | Value 1 | Value 2 | Is Smaller Than or Equal To Output |
---|---|---|---|
1 | 27 | 16 | FALSE |
2 | 9.0 | 9.0 | TRUE |
3 | " def" | "abc" | FALSE |
4 | 2018/01/01 | 2019/01/01 | TRUE |
5 | 3 | 8 | TRUE |
Use Case Scenario(s):
1. If a temperature is smaller than or equal to the setpoint, raise an alarm.
2. If an asset has been in an area for less than or equal to a specified time, raise an alarm.
Is Smaller Than
Function Description:
This function determines if the first value it receives is smaller than the second value. The function returns as true if the first value is smaller.
Function Structure:
![](/assets/images/commander/functions/is_smaller_than.png)
Figure 17 - Is Smaller Than
Inputs Required:
- Value 1 - A datapoint of any data type to be compared if it is smaller than input Value 2. This can be a boolean, a string, a number, etc.
- Value 2 - A datapoint of any data type to be compared with input Value 1. This should be the same data type as Value 1.
Output Expected:
- Boolean - Is Smaller Than function returns a boolean (true/false) value depending on whether the first value is smaller than the second value (true) or not (false).
Use Case Example(s):
Example | Value 1 | Value 2 | Is Smaller Than Output |
---|---|---|---|
1 | 15 | 20 | TRUE |
2 | 9.0 | 3.0 | FALSE |
3 | "abc" | "def" | TRUE |
4 | 2018/01/01 | 2019/01/01 | TRUE |
5 | 7 | 7 | FALSE |
Use Case Scenario(s):
1. If a temperature is smaller than the threshold then turn the aircon on.
2. If a vehicle senses that there is a low level of light in its surroundings it will automatically switch on the headlights.
Value Changed
Function Description:
This function analyses a single entity’s value/state to determine whether or not a new value/state received has changed compared to its previous value/state.
Function Structure:
![](/assets/images/commander/functions/value_changed.png)
Figure 18 - Value ChangedIs Smaller Than
Inputs Required:
- Value - This is an entity of any data type being assessed whether a new value coming in is different to the previous value for that entity.
Output Expected:
- Boolean - Value Changed function returns a boolean (true/false) value depending on the new value the entity receives. If the new value is not an exact match with the previous value for that entity, the function will output a true.
Use Case Example(s):
Example 1
Endpoint DateTime | Value | Value Changed Output |
---|---|---|
10:00:00 | 5 | - |
10:02:00 | 5 | FALSE |
10:04:00 | 5.8 | TRUE |
10:06:00 | 5.2 | TRUE |
10:08:00 | 4 | TRUE |
10:10:00 | 4 | FALSE |
10:12:00 | 4 | FALSE |
Example 2
Endpoint DateTime | Value | Value Changed Output |
---|---|---|
15:13:00 | True | |
15:17:00 | True | FALSE |
15:21:00 | False | TRUE |
15:25:00 | True | TRUE |
15:29:00 | True | FALSE |
15:33:00 | False | TRUE |
Use Case Scenario(s):
The function determines if the current live value of the entity being assessed matches the previously saved value for that entity. This therefore uses Commander system memory which should be taken into account when scaling solutions. |
1. Value Changed can be used in conjunction with the Point Of Interest (POI) functions to determine the movements of connected/mobile generators in a fleet. The POI function will return a location of a connected generator, thus the Value Changed function will output a false since the connected generator is stationary. Once the connected generator is being transported to a location, the POI function location will update and change depending on the generator’s whereabouts, thus causing the Value Changed function to output a true to indicate that the connected generator is on the move.
2. Monitoring the pH of an aquarium which is required to remain at 7.4. If this goes any higher or lower, raise an alarm.
3. At a fruit and vegatable wholesalers, the cold rooms need to be at a specific temperatue in order to maintain the freshness of the produce. If the temperature drops or rises drastically it should trigger an alarm or notification.
When Sequence Completes
Function Description:
Determines if a given sequence of conditions completes within the specified timespan. For it to return true, all the conditions received must be true within the set time limit. The timer starts when the first condition is true and resets if the time limit is exceeded.
Once a condition is added, a location for another condition will appear, giving the user the ability to add one or more conditions to the When Sequence Completes function. |
Function Structure:
![](/assets/images/commander/functions/when_sequence_completes.png)
Figure 19 - When Sequence Completes
Inputs Required:
- Timespan - The timespan required for the function application (HH:MM:SS).
- Conditions - A sequence of one or more conditions that are required to be true within the specified timespan.
Output Expected:
- Boolean - A boolean (true/false) value is returned depending on whether or not the outputs of the conditions within the function are met within the set timespan.
Use Case Example(s):
Endpoint Datetime | Timespan | Condition 1 | Condition 2 | Condition 3 | When Sequence Completes Output |
---|---|---|---|---|---|
2018/01/01 00:00:00 | 00:00:20 | False | False | False | FALSE |
2018/01/01 00:00:10 | 00:00:20 | True | False | False | FALSE |
2018/01/01 00:00:20 | 00:00:20 | True | True | True | FALSE |
2018/01/01 00:00:30 | 00:00:20 | True | True | True | TRUE |
2018/01/01 00:00:40 | 00:00:20 | True | True | False | FALSE |
Use Case Scenario(s):
1. A slot machine will return a value of true if within the specified time a complete set of matching pictures/icons/numbers is displayed. If the value returned is false within that specified time the slot machine will reset and give the player another chance.
2. When a customer is tagging in/out of the Gautrain station, the tag-in point returns a value of true if the card is still valid and has funds to allow for travelling. If the sequence of conditions are not met, the tag-in point will refuse access to the customer, informing them that the card is invalid or there are insufficient funds to proceed.
Between Utility Function
Function Description:
The purpose of this function is to determine whether a specific value falls between a range that has been configured. Based on this range, the function will then return true if the value is within the range, or false if it is not.
Function Structure:
![](/assets/images/commander/functions/between_utility_function.png)
Figure 20 - Between Utility Function
Inputs Required:
- Value - This is an entity of data type integer or decimal.
- Min - Lower boundary (minimum value).
- Max - Upper boundary (maximum value).
Output Expected:
- Boolean - A boolean (true/false) value is returned if the value falls between a range that has been configured (true) or not (false).
Use Case Example(s):
Example | Endpoint Value | Lower Boundary (Min Value) | Upper Boundary (Max Value) | Between Utility Output |
---|---|---|---|---|
1 | 54 | 20 | 100 | TRUE |
2 | 100.21 | 20 | 100 | FALSE |
3 | -10 | 10 | 11 | FALSE |
4 | 18 | 12 | 36 | TRUE |
5 | -2 | -13 | 5 | TRUE |
Use Case Scenario(s):
1. If a generator fuel level has less than 25% fuel remaining, then notify the site manager the fuel is low, If the fuel level is between 25% and 75%, then the fuel is at normal level and if the fuel is above this level, then the tank is full.
2. In aquariums, certain species thrive in specific temperature ranges. If the temperature check returns a true value within the specified temperature range it means the water temperature is ok and conducive for survival. If it is outside a specified range, then send an alarm “Water temperature out of range!