Logic block list
======================
.. note:: This is an apendix with extended information useful for
`writing logic for your gateway <../interface/logic-intro.html>`__.
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 | SOURCE | | tag - The tag value where the result is stored |
| | | device belonging to the same vendor. | | | to be reported to the cloud. |
| | | | | | deviceID - The device expecting this sensor data|
| | | | | | stream |
+-----------------+------------------------------------------+---------------+---------------------------------------------------+
| remote actuator | | An actuator on another ubiworx device | SINK | | tag - The tag value where the result is stored |
| | | device belonging to the same vendor. | | | to be reported to the child device. |
| | | | | | deviceID - The device reporting this actuator |
+-----------------+------------------------------------------+---------------+---------------------------------------------------+
| constant | | A constant value used as an input | SOURCE | | value - a numeric or boolean value |
| | | to other nodes | | |
+-----------------+------------------------------------------+---------------+---------------------------------------------------+
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 before 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 before 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.
.. image:: ../assets/images/logic/Sampledb-out.png
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.
.. image:: ../assets/images/logic/alarm-example.png
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 | | Extends all events by the specified time | | (1) boolean value | | time - milliseconds of delay |
| | | by specified number of milliseconds. | | | | | | |
+---------------+--------------------------------------------------+---------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------+
| oneshot | | A boolean delay line that delays in one | | Creating a longer event from a short event. For example, | | (1) boolean value | | time - milliseconds delay |
| | | direction only. On to Off transitions are | | turning on the lights in a room for a period of time | | | | |
| | | delayed but Off to On transitions are instant. | | because of a PIR activation. | | | | |
+---------------+--------------------------------------------------+---------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------+
| | | | | input or changing the time base of a sample stream. | | | | |
| resample | | Change the sampling rate of a data 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 | | One input – value to be accumulated | | Count - the number of samples over which summing occurs. |
| | | | | | fall rate to rain fall in 24 hrs or convert watts to | | | | |
| | | | | | kilowatt-hours. | | | | |
+-----------------+--------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------+------------------------------------------------------------------------------+
| | 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 | | Calculate rate of change of a value in a time series. | | One input – value to be analysed | | Count – this is the number of samples to be analysed |
| | | | of samples | | For example the number of degrees change per hour of a temperature sensor. | | | | |
+-----------------+--------------------------------------------------------------------------------------+------------------------------------------------------------------------------+-----------------------------------------+------------------------------------------------------------------------------+
| | 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 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.
.. image:: ../assets/images/logic/Ubiworx-average-block.png
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.