mO SharemO Share

Sensor tags

From SiteController version 1.9, there is an option to tag sensor data with live meta information. This can be used to add relational meta data to sensor data which can then be used later to search for certain categories in the time series on the cloud.

The idea is to add a set of tags to each sensor result of a sensor configured with a <tags> element. With each new result of that sensor, the sensor values referenced in the tags section in the configuration are collected and attached to the calibrated result.

 

SiteController XML

 

Imagine a configuration like this:

 

... <sensors> <sensor sensor_id="Temperature Engine 1"> <sensor_class>temperature</sensor_class> ... <tags> <tag_by_sensor sensor_id="Tag Sensor 1">OrderID</tag_by_sensor> # take the current calibrated value from "Tag Sensor 1" and put it as the value of the tag with the name "OrderID" into the tags info <tag_by_sensor sensor_id="Tag Sensor 2">JobID</tag_by_sensor> # put "Tag Sensor 2" value into tag with name "JobID" in tags section of the calibrated result of sensor "Temperature Engine 1" <tag_by_sensor sensor_id="Tag Sensor 3">BatchID</tag_by_sensor> # same for "Tag Sensor 3" value into tag "BatchID" in tags section of calibrated result of "Temperature Engine 1" </tags> <sensor_gateway sensor_gateway_id="sgw_values0"> # the calibrated value of "Temperature Engine 1" sensor itself is based on raw result in gateway "sgw_values0" ... <demux> <keys> <key>raw_temperature</key> # ... and key "raw_temperature" </keys> </demux> </sensor_gateway> </sensor> <sensor sensor_id="Tag Sensor 1"> <sensor_class>unknown</sensor_class> <sensor_gateway sensor_gateway_id="sgw_values1"> <demux> <keys> <key>raw_OrderID</key> </keys> </demux> </sensor_gateway> </sensor> <sensor sensor_id="Tag Sensor 2"> <sensor_class>unknown</sensor_class> <sensor_gateway sensor_gateway_id="sgw_values0"> <demux> <keys> <key>raw_JobID</key> </keys> </demux> </sensor_gateway> </sensor> <sensor sensor_id="Tag Sensor 3"> <sensor_class>unknown</sensor_class> <sensor_gateway sensor_gateway_id="sgw_values0"> <demux> <keys> <key>raw_BatchID</key> </keys> </demux> </sensor_gateway> </sensor> ... </sensors> <devices> <device device_id="Device1"> ... <sensor_gateways> <sensor_gateway sensor_gateway_id="sgw_values0"> ... </sensor_gateway> </sensor_gateways> </device> <device device_id="Device2"> ... <sensor_gateways> <sensor_gateway sensor_gateway_id="sgw_values1"> ... </sensor_gateway> </sensor_gateways> </device> </devices> ...

Workflow

Now imagine the following sequence of (slightly simplified) results of the various sensors and watch how the calibrated result is changing the tags:

Alternative workflow

Alternatively the same processing as a table:

Timestamp

Received Raw Result

Calibrated Results

Timestamp

Received Raw Result

Calibrated Results

1

raw_temperature=25.2

{"sensor_id":"Temperature Engine 1","value":25.2,"tags":[{"name":"OrderID","value":null},{"name":"JobID","value":null},{"name":"BatchID","value":null}],"timestamp":"1"}

2

raw_OrderID="1234"

{"sensor_id":"OrderID":"value":"1234","timestamp":"2"}

3

raw_BatchID="Berlin"
raw_JobID="Delivery"

{"sensor_id":"BatchID","value":"Berlin","timestamp":"3"}
{"sensor_id":"JobID","value":"Delivery","timestamp":"3"}

5

raw_temperature=31.5

{"sensor_id":"Temperature Engine 1","value":31.5,"tags":[{"name":"OrderID","value":"1234"},{"name":"JobID","value":"Delivery"},{"name":"BatchID","value":"Berlin"}],"timestamp":"5"}

6

raw_BatchID="Potsdam"

{"sensor_id":"BatchID","value":"Potsdam","timestamp":"6"}

11

raw_temperature=31.3

{"sensor_id":"Temperature Engine 1","value":31.3,"tags":[{"name":"OrderID","value":"1234"},{"name":"JobID","value":"Delivery"},{"name":"BatchID","value":"Potsdam"}],"timestamp":"11"}

Additional Information

The Site Controller supports up to 22 tags per tagged sensor. A sensor can be tagged by just adding a <tags> element to the sensor configuration and list the specific tag details inside of this element. Currently there is only one type supported.

<tag_by_sensor sensor_id="tag sensor id">tag name</tag> This will take the current value of the specified tag sensor as value for the tag with the specified name.

Note the calibrated sensor values of referenced sensors needs to have finished evaluation before the tagged sensor can use them. That especially means the sensor gateway must not produce a value for (in the above example) raw_temperature and raw_BatchID in the same result. Otherwise the tag value in the calibrated may or may not contain the new value from raw_BatchID.

If the referenced tag sensor value is not yet available at the time the result is evaluated, the tag value will be set to a null.

 

The tag names and the values in the referenced tag sensors needs to follow the String data type of InfluxDB line protocol standard. Furthermore currently, only printable ASCII characters (Characters from decimal 32 to 126 in http://www.asciitable.com/) are allowed.

Rest-API

In the following example it will be shown how to access the metadata through the Rest-API, more specifically Swagger UI. https://cloud.azeti.net/acp-service/api-doc

After authorizating on the page, head to /timeseries/queryUnmapped and click on try it out.

Query to find out all available tags used.

SHOW tag keys from Value

 

{ "results": [ { "series": [ { "name": "Value", "tags": null, "columns": [ "tagKey" ], "values": [ [ "LoadTag" ], [ "location_guid" ], [ "sensor_guid" ], [ "sensor_id" ] ] } ], "error": null } ], "error": null }

Read all information from a specific tag.

select * from Value where LoadTag<> null

 

{ "results": [ { "series": [ { "name": "Value", "tags": null, "columns": [ "time", "LoadTag", "event_id", "location_guid", "processing_level", "result_uid", "sensor_guid", "sensor_id", "value", "value_string" ], "values": [ [ 1573041163437, "0.54", "511a8922-4245-46b4-bbcc-854183aa7009", "2840456c-5abf-49f4-9018-c4f36a5f932c", 0, null, "aafae683-83b5-4ecc-98ea-6284dbab36ee", "Used_Memory_Pct", 15.8, null ] ] } ], "error": null } ], "error": null }

If you want to search for a specific value.

select value from Value where LoadTag= '0.54'