Logic block list¶
Note
This is an apendix with extended information useful for writing logic for your gateway.
Sink / source block summary¶
| Name | Description
|
Sink/Source | Parameters
|
|---|---|---|---|
| tag | An internal tag value
|
SINK / SOURCE | tag - The name of the tag name where the result
is to be retrieved from or stored.
|
| remote sensor | A sensor on another ubiworx
device belonging to the same vendor.
|
SOURCE | tag - The tag value where the result is stored
to be reported to the cloud.
deviceID - The device expecting this sensor data
stream
|
| remote actuator | An actuator on another ubiworx device
device belonging to the same vendor.
|
SINK | tag - The tag value where the result is stored
to be reported to the child device.
deviceID - The device reporting this actuator
|
| constant | A constant value used as an input
to other nodes
|
SOURCE | value - a numeric or boolean value
|
Input blocks¶
Tag block¶
The tag block is the most generic type of block that exists. It simply mirrors the value in a ubiworx tag.
A tag can be used as an input (value is read from a tag) or an output (value is stored to a tag).
Tags beginning with a dollar sign are read-only system tags and are used to retrieve system information such as time of day, sunrise time and so on. Tags beginning with underscore are reserved for internal use. Any other tag is considered to be a user tag and can be modified by rules or by any other module in the system.
Tags may also refer to sensors or actuators that are listed in the sensor list panel of the broker user interface. These sensors and actuators may be physical or virtual. A physical input tag may refer to a local input on the local system. For example, a GPIO input pin or an Xbee radio PIR. A physical output defines a local output on the local system. For example, a GPIO output pin or an Xbee radio controlled relay. Physical actuators and sensors are created in the sensor list pane of the gateway dashboard.
Tags may also be “virtual” or “local” sensors If a sensor is created of type “LocalActuator” with an id of “local-tag” the properties panel of the dashboard for the gateway will allow a user to set a value for this actuator from the cloud, or it can be set by an API request. see [API](API “wikilink”). This value is then received by the gateway and placed in the tag “local-tag”. This value can be used as the input to a logic sequence. For example, it could be the temperature control for a heating system.
Conversely, virtual sensors are used to create derived value sensors for transmission to the cloud. If logic is used to calculate a value and that value is then stored in a tag called “local-tag”, then a sensor of type “LocalSensor” can be created with an id of “local-tag” to periodically send that value to the cloud.
Remote sensor block¶
Remote sensors and actuators refer to instances of data streams provided by other ubiworx devices. They have two fields - name and deviceID. The deviceID field contains the name of a remote gateway. The name field refers to the name of a tag on the remote gateway. This block subscribes to any updates made to the remote tag and updates its output whenever the remote tag changes. A gateway can read any tag on any gateway that has the same vendor ID as the gateway has but cannot read or modify tags belonging to other vendors.
Constant¶
The constant block is simply a fixed value. It is a way of putting a value into a tag. The output of a constant block is updated once at startup and is never modified again after that.
SampleDB input block¶
The sampleDB Input block is used to query a histdb file. The file is assumed to exist and to have been created by a corresponding sampleDB Output block. If the file doesn’t exist, then no output is created.
This block does not have any inputs. It starts a periodic timer which internally kicks off a query using the configured parameters. The block will query the database for time interval from now less the interval to now. For example, if the time now is 15:10 and the interval is 5 minutes then the query will ask for samples from 15:05 to 15:10.
The query block generates one output every time it runs. A parameter is used to specify how the data is aggregated before output.
For each of the aggregations functions MIN, MAX, SUM, FIRST, LAST or AVERAGE, the block operates on the samples retrieved within the given time period range.
For the DELTA aggregation function, the block takes the sample immediately <b>before</b> the start of the time period and the last sample of the time period and subtracts one from the other to calculate the difference. This is done to ensure successive delta operations are consistent and deltas from smaller time ranges add up to the same result as a single delta taken from a larger range.
The following configuration parameters are available:
| Name | Description
|
|---|---|
| name | The name of the block
|
| db-name | The file name of the persistent storage
|
| interval | The amount of time between queries.
The block will execute at this interval.
|
| interval-unit | The unit of the interval field.
This is a drop down list offering
a choice of units from milliseconds to years.
|
| from | The from field specifies the start of the query range.
It is relative to the time now.
|
| from-unit | The unit of the from field.
This is a drop down list offering a choice of units
from milliseconds to years.
|
| to | The to field specifies the end of the query range.
It is relative to the time now.
|
| to-unit | The unit of the to field.
This is a drop down list offering a choice of units
from milliseconds to years.
|
| filter | The function to be used to convert a list of samples
to one output.
A drop down list allows selection of MIN, MAX, SUM, FIRST
LAST, DELTA or AVERAGE.
This function can only be used with numeric data.
|
SampleDB-since input block¶
The sampleDB-since Input block is used to query a histdb file. The file is assumed to exist and to have been created by a corresponding sampleDB Output block. If the file doesn’t exist, then no output is created.
This block does not have any inputs. It starts a periodic timer which internally kicks off a query using the configured parameters. The block will query the database for all data stored since the beginning of a specified parameter (this hour, today, this week, etc) up to the current time. For example, if the time now is 15:10 and the interval is 5 minutes and the since field is set to “today” then the query will examine all samples from 0:00 to 15:10 today.
The query block generates one output every time it runs. A parameter is used to specify how the data is aggregated before output.
For each of the aggregations functions MIN, MAX, SUM, FIRST, LAST or AVERAGE, the block operates on the samples retrieved within the given time period range.
For the DELTA aggregation function, the block takes the sample immediately <b>before</b> the start of the time period and the last sample of the time period and subtracts one from the other to calculate the difference. This is done to ensure successive delta operations are consistent and deltas from smaller time ranges add up to the same result as a single delta taken from a larger range.
The following configuration parameters are available:
| Name | Description
|
|---|---|
| name | The name of the block
|
| db-name | The file name of the persistent storage
|
| interval | The amount of time between queries.
The block will execute at this interval.
|
| interval-unit | The unit of the interval field.
This is a drop down list offering
a choice of units from milliseconds to years.
|
| since | The since field specifies the start of the query range.
It is not a relative field but is a fixed point in time.
It can be one of this hour, today, this week, this month or this year.
|
| filter | The function to be used to convert a list of samples to one output.
A drop down list allows selection of MIN, MAX, SUM, FIRST, LAST, DELTA
or AVERAGE. This function can only be used with numeric data.
|
Schedule block¶
The schedule block is used to control when events occur. Each schedule block has a begin time, an end time and check box for each day of the week. The schedule block sets its output to one when the current time is greater than or equal to the start time, is less than the end time and the current day of the week is ticked.
Several schedule blocks can be wired together with AND or OR logic to create more complex schedules. See [examples](examples “wikilink”).
Output¶
Tag block¶
see the equivalent input block
Remote actuator block¶
Remote sensors and actuators refer to instances of data streams provided by other ubiworx devices. They have two fields - name and deviceID. The deviceID field contains the name of a remote gateway. The name field refers to the name of a tag on the remote gateway. This block subscribes to any updates made to the remote tag and updates its output whenever the remote tag changes. A gateway can read any tag on any gateway that has the same vendor ID as the gateway has but cannot read or modify tags belonging to other vendors.
SampleDB output block¶
The sampleDB Output block creates an entry in a histdbfile. If the histdb file does not exist, it will be created.
This block has one input and does not have any outputs. It starts a periodic timer which internally kicks off a query using the configured parameters. The block will read the input value and store a sample to the database every time interval.
The parameters are as follows:
| Name | Description
|
|---|---|
| name | The file name of the persistent storage
|
| datatype | A drop down list selection of either “TEXT” or “NUMBER”.
|
| interval | The amount of time between queries.
The block will execute at this interval.
|
| interval-unit | The unit of the interval field.
This is a drop down list offering a choice of units from milliseconds to years.
|
| duration | The total amount of time stored in the database.
This parameter is used to determine the size of the file.
|
| duration-unit | The unit of the duration field.
This is a drop down list offering a choice of units from milliseconds to years.
|
| max-duration | The number of histdb files that may be created.
|
Alarm block¶
- This block triger an alarm with the specified message and category whenever the input gets a non 0 value
- The category is free
- Into the alarm text you are able to insert a tag value by writing @TAG_NAME@ at any place.
Arithmetic, boolean and comparative blocks¶
Arithmetic, Boolean and Comparative blocks perform simple calculations or comparisons of their inputs and update their outputs accordingly. The following table summarises their functionality.
| Name | Description |
|---|---|
| and | A simple and gate. All inputs and outputs must be boolean.
Numeric values are treated as false if zero and true if non zero.
|
| or | A simple or gate. All inputs and outputs must be boolean.
Numeric values are treated as false if zero and true if non zero.
|
| not | A simple invertor. All inputs and outputs must be boolean.
Numeric values are treated as false if zero and true if non zero.
|
| add | Adds two inputs together.
All inputs and outputs are numeric.
|
| subtract | Subtract one input from another.
All inputs and outputs are numeric.
|
| multiply | Multiply two inputs together.
All inputs and outputs are numeric.
|
| divide | Divide one input by another.
All inputs and outputs are numeric.
If the second input is zero, the output is simply set to “divide by zero!”.
|
| greater | A simple numeric comparator.
Output is true if first input is greater than second input.
|
| less | A simple numeric comparator.
Output is true if first input is less than second input.
|
| equal | A simple numeric comparator.
Output is true if first input is equal to the second input.
|
Timing blocks¶
Timing Blocks are used to create time events in a logic stream. Sometimes it may be desirable to convert an asynchronous event stream to a synchronous periodic stream. This can be done with the “resample” block.
In other cases it may be desirable to delay or stretch an event. The “delay” and “oneshot” blocks may be used for this.
A common usage of “oneshot” blocks is to control lighting in response to movements detected by a PIR or other occupancy sensor.
| Name | Description
|
Use case
|
Inputs
|
Parameters
|
|---|---|---|---|---|
| delay | A boolean delay line. Delays input state
by specified number of milliseconds.
|
Extends all events by the specified time
|
(1) boolean value
|
time - milliseconds of delay
|
| oneshot | A boolean delay line that delays in one
direction only. On to Off transitions are
delayed but Off to On transitions are instant.
|
Creating a longer event from a short event. For example,
turning on the lights in a room for a period of time
because of a PIR activation.
|
(1) boolean value
|
time - milliseconds delay
|
| resample | Change the sampling rate of a data stream.
|
input or changing the time base of a sample stream.
Creating a periodic sample output rate from an asynchronous
|
(1) boolean value
|
interval - output interval in milliseconds
|
Aggregation and conditioning blocks¶
These blocks are used to perform calculations over a number of samples to perform filtering or conditioning functions on the data stream.
They typically use a sliding window of “n” samples where n is configurable for each block. They are typically event driven and execute whenever the input changes.
| Name | Description | Use case | Inputs | Parameters |
|---|---|---|---|---|
sum
|
This block performs a summing or integration function over an incoming data stream
|
Converting rate information to totals. E.g. Convert rain
fall rate to rain fall in 24 hrs or convert watts to
kilowatt-hours.
|
One input – value to be accumulated
|
Count - the number of samples over which summing occurs.
|
average
|
The average block performs a rolling average over a number of samples
|
Smoothing noisy data / eliminating high frequency changes.
|
One input – value to be averaged
|
Count – this is the number of samples to be averaged
|
min
|
Find the minimum value in a rolling number of samples
|
Identifying lowest value in a time series
|
One input – value to be analysed
|
Count – this is the number of samples to be analysed
|
max
|
Find the maximum value in a rolling number of samples
|
Identifying highest value in a time series
|
One input – value to be analysed
|
Count – this is the number of samples to be analysed
|
delta
|
Find the difference between the first value and the last value in a rolling number
of samples
|
Calculate rate of change of a value in a time series.
For example the number of degrees change per hour of a temperature sensor.
|
One input – value to be analysed
|
Count – this is the number of samples to be analysed
|
stddev
|
Find the standard deviation over a number of samples in a sliding window.
|
Calculate the stability of a reading.
|
One input – value to be analysed
|
Count – this is the number of samples to be analysed
|
Average block implementation¶
- The average block is triggered either by a change of its input only.
- An array large enough to hold <count> samples is declared and used as a ring
- Every time a new sample arrives, it is added to the head of the ring. If the ring is full, the tail is discarded before adding to the head.
- The average is calculated over the number of samples in the ring and the output is set to this value.
- If the number of samples is less than the count, e.g. at startup, then the average is still calculated, just using a reduced set.
- Time of arrival of samples is irrelevant and ignored.
Lua block¶
- This block allows to write lua code for processing the input data.
- The two inputs are available in the lua code as input1 and *input2
- This block should contanin a return for the resulting data
Example:
-- Convert inputs to number
input1 = tonumber(input1)
input2 = tonumber(input2)
-- Return a diferent value depending on input values
if (input1 > 30) and (input2 < 10) then
return (input1 + input2) / 2
end
return input1 + input2
Switch block¶
- This block allows data from first input to flow through it if second input is not 0
- Useful, for example, for controlling a high speed data flow connected to an asynchronous sensor, so the gataway only send data to the broker when it is relevant.