Usually, RAW values are included in the payload without any encoding (Literal), alternatively they may use the standard JSON representation; and in other cases the value might be encoded as a binary value (e.g., sending MODBUS registers).
Literal
The value is encoded as a simple string.
{
"data": {
"stringValue": "FooBar",
"booleanValue": "true",
"integerValue": "123456",
"floatValue": "123.456"
}
} The system automatically converts the incoming string values according to the target metric types. Pay attention to configure the right metric type, the value maybe discarded during data ingestion in the case it cannot be converted to the target type (e.g. partInt("fooBar")).
When sending values to the remote products, it is suggested to use the Literal (JSON) encoding, if possible.
Literal (JSON)
This encoding is automatically supported when receiving RAW data, but can be explicitly defined when sending data to the remote things (e.g. configuration parameter). By using this encoding, boolean and number values are encoded with the standard JSON encoding.
{
"data": {
"stringValue": "FooBar",
"booleanValue": true,
"integerValue": 123456,
"floatValue": 123.456
}
} In case of numbers, the values -INF, INF or NA cannot be sent, even if supported by the JSON specification. The presence of these values will cause the message to be discarded.
Binary Int / Binary Hex
The value is encoded by using a binary representation, which can be an integer or a hex string.
From the binary encoded value, you can also specify to extract a single bit or a sub-sequence of bits.
For example, if you have a MODBUS register that provides several boolean flags, the metric will be of type BOOLEAN and the binary encoding will have to read only one bit at a given position (e.g., position=3, length=1).
To do this, you can specify:
Binary position: the position (zero-based) of the initial bit to be read.
Binary length: the number of bits to be read.
Binary byte order: the order in which the bytes are to be read (Little-endian or Big-endian).
For instance, consider the following sequence of bits and its integer representation.
10010001 → 145 (91 in hex)
In order to extract the bits, you need to use: Binary position=0, Binary length=1 → TRUEBinary position=1, Binary length=1 → FALSEBinary position=3, Binary length=1 → TRUEBinary position=7, Binary length=1 → TRUE
A binary value allows encoding multiple information into a single published data, that on the cloud side is decoded, and each sub-information is addressed to a different metric.
This approach has some aspects to be considered.
Lower bandwidth consumption in data transmission, as the payload size is reduced.
If the gateway accesses a MODBUS channel, no further data processing is required on the edge, and the register value can be published as is.
Assuming that you only publish a data upon modification, it only takes a single bit to change for the entire value set to have to be republished.
This has the side effect of consuming more DPH for data ingestion on the cloud side.
You can save DPH by enabling the Discard consecutive equal values on the RAW metrics.In case the binary value contains events statuses information, you can avoid defining a metric for each single bit, and use the Bit at Position predicate inside event conditions.
BLOB Values
In case of RAW metrics of type BLOB, the payload must include two fields whose names are declared in the Mapping section of the metric.
{
"data": {
"<CONTENT_FIELD>": "iVBORw0KGgoAAAANSUhEUgAAAB........SuQmCC",
"<FILE_NAME_FIELD>": "log.txt"
}
} CONTENT_FIELD: the contents of the file encoded in Base64.
FILE_NAME_FIELD: the original file name.