Custom Encoders/Decoders

To Add a Custom Encoder/Decoder:

In the Workbench, expand a project and the expand the Internet of Things node. Right-click on the Custom Encoders/Decoders node, as shown below, and then click on Add Encoder/Decoder.

Add Encoder/Decoder from Project Explorer in the Workbench

-OR-

Select Custom Encoders/Decoders then click on the Add Encoder/Decoder button (shown below) in the Edit section of the Home ribbon in the Workbench.

Add Encoder/Decoder Button

This opens the Custom Encoder/Decoder properties window, as shown below, in the Workbench. Enter a Name for the Custom Encoder/Decoder in the top text entry field.

Custom Encoder/Decoder Properties in the Workbench

General Settings

Plugin - Use the pulldown menu to select from available plugins (e.g. CustomJson).
Message Type - Use the pulldown menu to select from 'Multiple values in the "Values" array of the message', 'One value for each message', Multiple values for each message', or "The whole message is a dataset".
Value Format - Enter the value format in the text entry field. Sample text is provided to demonstrate the syntax. Click on the Add keyword link to open the Custom JSON Encoder Format Keywords in order to select a keyword for the custom format for each property (Value, Message, Write). Click on the Set default format link to reset back to the default format shown. Click on Auto indent to automatically indent the message text.

If you selected the Message Type of 'Multpile values in the "Values" array of the message', you can now edit the Message Format section, utilizing the same links specified in 'Value Format' above. If you selected 'One value for each message', you will see the contents of the Value Format reflected in the Message Format field in real time.

Use different format for writing - Clicking this checkbox allows you to provide a different Write Format, utilizing the same links specified in 'Value Format' above.

When you have completed your settings, click on the Apply button. Click on Close to return to the Workbench. Your new Custom Encoder/Decorder will now appear in the Project Explorer.

JSON Message Format

1. Simple Message Format (one value per message)

This is a simple format for the JSON message that can be published to an MQTT broker and accepted by an ICONICS subscriber. While it can result in a large total message count and is not very efficient, it is easy to set up and may be suitable for devices with very datapoints or infrequently changing data.

Message Structure Example Message

{ {

"id": "[tagname]", "id": "CurrentOccupancy",

"v": "[value]", "v": "7"

"q": "[quality]", "q": "true",

"t": "[timestamp]" "t": "1580413177050"

} }

2.Standard Message Format (multiple values per message)

A more common format for the messages sent by the publisher is to include multiple tag updates in a single message. This format is similar to the simple format above, but groups multiple data updates into a single message. This will be more efficient in regard to the total message count and is well suited for devices which have and internally defined publish rate which would allow for publishing of multiple values at a standard time interval. The format can be extended to include other information about tags as needed.

Message Structure Example Message

[ [

{ {

"id" : "[tagname1]", "id" : "Temperature1",

"v" : "[value1]", "v" : "-4.256",

"q" : "[quality1]", "q" : "true",

"t" : "[timestamp1]" "t" : "160575173869"

} , { } , {

"id" : "[tagname2]", "id" : "Temperature2"

"v" : "[value2]", "v" : "-6.159",

"q" : "[quality2]", "q" : "true",

"t" : "[timestamp2]" "t" : "1605751173870"

} , {…} }

] ]

3.Standard Message Format (multiple values with common attributes)

This format is similar to the standard format of multiple updates per message, but additionally allows for certain properties to be grouped globally for all datapoints in the message. By publishing messages in this format, it is assumed that all datapoints within the array share the attributes of the root object, unless explicitly overridden within that value. It can be an efficient format in terms of volume of data per message as it eliminates redundant data in the JSON message.

Message Structure Example Message

{ {

"dvcname" : "[dvcname]", "dvcname" : "Controller6" ,

"t" : " [timestamp] ", "t" : "1605751173869" ,

"v" : "[quality]", "v" : "true" ,

"values" : "values" :

[ [

{ {

"id" : " [tagname1] ", "id" : "Temperature1" ,

"v" : " [value1] " "v" : "-4.256"

} , { } , {

"id" : " [tagname2] ", "id" : "Temperature2" ,

"v" : " [value2] " "v" : "-6.159"

} , {…} }

] ]

} }