Custom Parser

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

When a parser is used in a subscriber, the following objects will become available:

• $.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. 

MQTT Client Full Product Details