|
<< Click to Display Table of Contents >>
Syntax of a JSON Template |
To extract or assemble the content of a message, users must declare a template, which allows specifying the format of this message and which parts must be transformed into data. Each template must use keywords placed in the position of the values to extract. The available keywords are described on the next table.
Available keywords for templates
Keyword |
Description |
|---|---|
TS_TEXT(format) |
Timestamp, in Text format, used as the timestamp for a Block Tag or I/O Tag. The meaning of each field is described on table Available options for the TS_TEXT keyword |
TS_UNIX |
Timestamp, in seconds since 1970, or UNIX format. This value can be a number or a text, and it is used as the timestamp for a Block Tag or I/O Tag, that is, 1504198675 or "1504198675" |
QL_OPC |
Quality, in OPC DA standard, using 1 (one) byte. This value is used directly as the quality value in a Block Tag or I/O Tag, without transformation. For more information, please check table OPC DA standard |
QL_BOOL |
Quality in Boolean standard. If the value is greater than 0 (zero) or the "true" or "TRUE" expression, quality is good. If the value is 0 (zero) or the "false" or "FALSE" expression, quality is bad |
E3VAL |
Specifies a value extracted in the sequence that it occurs for a Block Tag, each value in a Block Element. If there is only one E3VAL value in a message, the template can also be used with an I/O Tag |
DUMMY |
A variable field, but whose value must not be sent to I/O Tags |
Repeat_E3VAL |
A keyword that can only be used inside an array in JSON format to indicate that repeated elements inside that array must be processed independently by this Driver, returning a reading for each set. A template can have this keyword only once |
Available options for the TS_TEXT keyword
Option |
Description |
|---|---|
%a |
Abbreviated weekday, in English |
%A |
Full weekday, in English |
%b |
Abbreviated month, in English |
%B |
Full month, in English |
%C |
Century |
%d |
Day of the month, starting with 0 (zero) |
%e |
Day of the month, starting with a space |
%f |
Milliseconds, from 0 (zero) to 999 |
%h |
Hour in 12-hour format |
%H |
Hour in 24-hour format |
%m |
Month |
%M |
Minute |
%p |
AM or PM |
%S |
Seconds |
%y |
Year with two digits |
%Y |
Year with four digits |
%Z |
Timezone, an international code that converts time to a GMT (Greenwich Mean Time) format |
%+ |
Offset of GMT time in the format ±HH:MM |
The next code contains examples of timestamps formatted by the TS_TEXT keyword.
"2014-07-11T15:26:37Z" -> "TS_TEXT(%y-%m-%dT%H:%M:%SZ)"
"Mon Jul 10 11:04:47 BRT 2017" -> "TS_TEXT(%a %b %d %H:%M:%S %Z %Y)"
"2018-05-02T10:29:28.622-02:00" -> "TS_TEXT(%Y-%m-%dT%H:%M:%S.%f%+)"
Bit |
7 |
6 |
5 |
4 |
3 |
2 |
1 |
0 |
Description |
Q |
Q |
S |
S |
S |
S |
L |
L |
Available options for the OPC DA standard
Option |
Description |
|---|---|
Two quality bits |
|
SSSS |
Four sub-status bits |
LL |
Two limit bits |
Possible values are 0: BAD, 1: UNCERTAIN, or 3: GOOD |
|
SSSS |
Possible values are 0: BAD_NONSPECIFIC, 1: BAD_CONFIGERROR, 2: BAD_NOTCONNECTED, 3: BAD_DEVICEFAILURE, or 4: BAD_SENSORFAILURE |
SSSS |
Possible values are 0: UNCERT_NONSPECIFIC, 1: UNCERT_LASTUSABLEVALUE, or 4: UNCERT_SENSORNOTACCURATE |
SSSS |
Possible values are 0: GOOD_NONSPECIFIC, 1: GOOD_LOCALOVERRIDE, or 6: GOOD_NONSPECIFICLOCALTIMESTAMP |
LL |
Possible values are 0: FREE, 1: LOW, 2: HIGH, or 3: CONST |
A file in JSON format containing an array with multiple data sets must include the Repeat_E3VAL keyword in the template right after the opening bracket of that array, according to the next example.
{
"MessageType": "DUMMY",
"TagData": [
Repeat_E3VAL {
"Temperature": "E3VAL",
"Humidity": "E3VAL"
}
],
"MessageDesc": "DUMMY"
}
In this case, when receiving a message with 2 (two) data sets, for example, the OnRead event of a Block Tag is triggered for each set, as shown in the next code.
Sub [Sensor-001_OnRead]()
Application.Trace Item("Temperature").Value
Application.Trace Item("Humidity").Value
End Sub
If other E3VAL-type values are declared before or after a Repeat_E3VAL-type value, these are replicated for each set, with the Repeat_E3VAL-type value always as the last in the receiving Block Tag, according to the next example.
{
"MessageType": "E3VAL",
"TagData": [
Repeat_E3VAL {
"Temperature": "E3VAL",
"Humidity": "E3VAL"
}
],
"MessageDesc": "E3VAL"
}
A Block Tag with the Block Elements Type, Description, Temperature, and Humidity can generate, for each OnRead event, values according to the next code.
"Test";"Description";11;12 => First OnRead event
"Test";"Description";14;66 => Second OnRead event
"Test";"Description";70;55 => Third OnRead event
If users want to trigger an OnRead event for each set, a template can be declared without a Repeat_E3VAL-type value, using only one E3VAL-type keyword to capture the array, according to the next code.
{
"MessageType": "DUMMY",
"TagData": "E3VAL",
"MessageDesc": "DUMMY"
}
In this case, the received array is expanded based on the number of elements, resulting in a single reading on the OnRead event, in the format of the next example.
array(11, 12); array(14, 66); array(70, 55) => Single OnRead event
If a template contains more than one E3VAL-type keyword, that is, non-DUMMY, the array is not expanded, according to the next example.
{
"MessageType": "E3VAL",
"TagData": "E3VAL",
"MessageDesc": "E3VAL"
}
This reading is performed on a single OnRead event, in the format of the next example.
"Test"; array(array(11, 12), array(14, 66), array(70, 55)); "Description"=> Single OnRead event