Custom Parser

Updated on 16 Jul 2025
5 Minutes to read

Article summary

Did you find this summary helpful?

Thank you for your feedback!

A custom parser allows users to write their own parser using Javascript code. This allows MQTT Client to support virtually any payload possible. There are several utilities that can be used to simplify writing code when using custom parsers, as well as some additional requirements that users must follow in order for the parsing to be successful. These are listed in the following sections:

Utilities

All scripts in custom parsers have access to these utilities:

Buffer

This represents a Node.js Buffer object. This can be used to manipulate a Buffer instance directly, for example when the serialization format is set to None and deserialization has not occurred. More information about buffer can be found in the Node.js Buffer Section.

Moment

Moment.js is a Javascript library used to easily format and parse timestamps. The provided version of Moment also includes Moment timezone, by using moment.tz(). More information can be found at Moment.js and Moment Timezone.

Sprint

Sprintf is a function used to format strings using a format string and one or more variables. It is similar to the behaviour of the C++ sprintf function. Format strings can use placeholders by means of special characters preceded by a % character. These placeholders will be substituted by variables passed as arguments. This function has the following signature: sprintf(format, …args)

See below for the valid placeholders for format strings.

Integer: %d or %i
String: %s
Binary: %b
JSON: %j
ASCII character in decimal: %c
Scientific notation: %e
Floating point: %f
Fixed point: %g
Octal: %o
Unsigned integer: %u
Hexadecimal lowercase: %x
Hexadecimal uppercase: %X
Node buffer: %r

All formats that admit decimal numbers, such as floating point or scientific notation, can be configured to specify the required number of decimals to be displayed by using the format %.xY, where x is the number of decimals, and Y is the format used (f, for floating point; e, for exponential, etc.). For example, to show a floating-point number with 2 decimals, the following format must be used: %.2f.

$.logger
The $.logger object is used to log messages to disk, which can be used for both debugging and informative purposes. The log file can be found at N3uron/log/MqttClientInstance/. It is shared by both the internal module code and any messages written by the custom parsers. The following are all functions that can be used to write to the log file:

$.logger.error(message, …arguments)
$.logger.warn(message, …arguments)
$.logger.info(message, …arguments)
$.logger.debug(message, …arguments)
$.logger.trace(message, …arguments)

Each of these functions takes a format string (in the same format as sprintf) and an optional list of arguments used to replace the placeholders in the format string.

Subscriber Parser

A Subscriber Custom Parser lets you transform any inbound MQTT messages into N3uron tag events by writing JavaScript code.

Steps to Create Your Custom Parser Script

Access the MQTT Client Configuration and choose the appropriate Subscriber agent configuration.
Configure the message format.
- Encoding: Selects which format to use to decode the message.
  - UTF8: Decodes the message as a UTF8 string.
  - Binary: Decodes the message as a binary buffer.
  - Base64: Decodes the message as a Base64 encoded string.
  - Hex: Decodes the message as a hexadecimal string.
- Compression: Selects which algorithm to use to decompress the received message.
  - None: No compression is applied (data is sent as-is).
  - GZip: Compresses data using the GZip algorithm.
  - Deflate: Uses the Deflate compression method.
- Deserialization: Selects which serializer to use to transform the message into a JavaScript object.
  - None: No serializer will be used and the message will be passed to the parser as is. This can be used to implement custom serializers by using a custom parser to both serialize the message and parse the data.
  - JSON: The message will be deserialized as a JSON string and the resulting JavaScript object will be passed directly to the data parser.
  - Protocol Buffers: The message will be deserialized using Protocol Buffers. If the message conforms to the given protobuf Message definition, it is deserialized and the resulting object is sent to the data parser. Otherwise, an error will be raised and no parsing will occur.
Enable a custom parser by selecting the Data parser and setting the Type to Custom.
Open the javascript editor by clicking the button next to the Script field.

Write a JavaScript script to build a custom parser tailored for specific requirements. Within the Subscriber Custom Parser, the objects $.input and $.output have the following structure:

$.input: This represents the input message received from the MQTT broker. The message type can either be a Javascript object (if it has been deserialized using JSON or Protocol Buffers) or a binary Buffer.
$.output: This is a Javascript Array and is where tag events must be stored in order for them to be applied to tags. Since this is a standard Array, all array methods are available. More information about the different methods can be found in the Array section. One of the most important methods is the Array.prototype.push method, which can be used to push tag events into the output array by executing $.output.push(tagEvent). Each tag event must follow the below format:
```
{
  "tag": "/Group/Tag",
  "value": 1234,
  "quality": 123,
  "ts": 1586353800000
}
```
Tag: This value can either be the full tag path (if an alias has not been created) or the tag alias, as defined in the tag configuration section.
Value: The value of this tag event. This can be a number, a string, or a boolean, depending on the tag type.
Quality: The OPC quality of this tag event, displayed as a number between 0 and 255. This follows OPC quality standards, where tag qualities between 0 and 63 are considered bad, 64 to 127 uncertain, and 192 to 255 good. All ranges are inclusive.

Timestamp: The timestamp of this tag event, displayed in the UNIX Epoch with milliseconds format.

Example of a custom parser script:

/*************************************************************************************************************************
* This script is based on this type of input:
* [
*   { 
*     t: TAG_ADDRESS,
*     v: TAG_VALUE,
*     q: TAG_QUALITY,
*     ts: yyyy-MM-ddTHH:mm:ss.sssZ
*   },
*   ...
* ]
* ************************************************************************************************************************/

$.logger.debug("Parsing %d events", $.input.length);
// Declare a variable to create the JS object wanted.
const response = [];

// Iterate over all events in $.input
for (const event of $.input) {
  // Event data:
  //  { 
  //     t: TAG_ADDRESS,
  //     v: TAG_VALUE,
  //     q: TAG_QUALITY,
  //     ts: yyyy-MM-ddTHH:mm:ss.sssZ
  //  }

  // Convert to:
  //  {
  //    tag: TAG_ADDRESS,      // This value is used to choose which tag will be updated. It can either be the tag address of the tag (defined in the tag configuration), or the path of the tag **if** the tag address is empty 
  //    value: TAG_VALUE,      // This is the value used to update the tag. It can be any value.
  //    quality: TAG_QUALITY,  // This is the quality of the tag for this event. It has to be a number from 0 (Bad) to 192 (Good).
  //    ts: EPOCH_TIMESTAMP    // This values is used as the timestamp of the event. It has to be a number in epoch format with milliseconds.
  //  }
  response.push({
    tag: event.t,
    value: event.v,
    quality: event.q,
    ts:  Date.parse(event.ts)
  });
}

// Send the output
$.output = response;

Save the script and test the Subscriber Custom Parser to ensure that the incoming events correctly update the tags.

Note:

For more information about parsing, go to Parsing Examples.

MQTT Client Full Product Details

Was this article helpful?

What's Next

Custom Payload

Table of contents

Utilities
Subscriber Parser