javascript_parsers

WIKA

Welcome to the WIKA LPWAN device parser monorepo

This repository ‘javascript_parsers’ contains the JavaScript parser for our LPWAN devices:

The JavaScript parser converts the raw byte payload of our devices into a JavaScript object (defined in the uplink.schema.json file). The parser for building the raw byte downlink payloads are available for some devices as well and are defined in the downlink.schema.json file.

All our JavaScript parser scripts follow the specification LoRaWAN® Payload Codec API Specification TS013-1.0.0.

Release Structure

To make the parsers easily accessible for usage in gateways and network server, a zip file is generated which contains all the parsers and the required files to use them. The zip file is generated by the build process and can be found in the release folder of the repository. All supported devices are included in the zip file. The zip file contains a folder for each device with the following structure:

zip
├── <device name directory>
│   ├── downlink.schema.json    # contains the downlink object specification (only for some devices)
│   ├── driver.yaml             # contains some meta information
│   ├── examples.json           # contains some input and output payload examples for unit testing
│   ├── index.js                # contains source code of the payload parser
│   ├── metadata.json           # contains some meta information about the parser
│   ├── uplink.json             # contains a complete object example
│   ├── uplink.schema.json      # contains the output object specification
│   └── README.md               # contains information about the sensor
└── ...other devices

Usage

Usage in a project

Some of the parsers are available as npm packages. To use them, you can install the package via npm and use the parser in your project.

npm i @w2a-iiot/parsers

Afterwards the can be used in your project.

import { NETRIS2Parser } from '@w2a-iiot/parsers'

const {
  decodeUplink,
  encodeDownlink,
  adjustRoundingDecimals
} = NETRIS2Parser()

adjustRoundingDecimals(2)

const decoding = decodeUplink(input)

console.log(decoding)

They encapsulate the raw parsers and add some additional functionality on top, for example minifying the downlink frames.

Usage in a gateway or network server

New JavaScript Parsers (3.x.x and newer)

The javascript parsers are in the process of being rewritten in typescript. In addition the parsers will be made available as a npm package. With the new parsers, there is no need to modify the index.js file before you can use the JavaScript parsers as they let you define the measuring ranges of the sensor via a function. Additionally, the utility function adjustRoundingDecimals to adjust the amount of decimals of the output values. To use those, just add the respective function call after the parser.

/**
...
raw minified parser
...
*/

adjustRoundingDecimals(2);
// adjust the measuring range of channel 0 to -40 to 100
// returns an error string if the given channel id cannot be found
const undefinedOrErrorString = adjustMeasurementRange(0, {
  start: -40,
  end: 100
});

if(typeof undefinedOrErrorString === 'string') {
    console.error(undefinedOrErrorString);
}

const decoding = decodeUplink(input);

console.log(decoding);

Currently implemented parsers:

For more information about how to include the new parsers in your project, please refer to the quick start guide and the examples.

Note: The decodeHexString and decodeBase64String functions are not available in the new parsers as the were made to be compatible with browser environments, which don’t support the nodejs Buffer class.

Legacy JavaScript Parsers (2.x.x and older)

ATTENTION

!!! You must modify the index.js file before you can use the JavaScript parsers !!!

Each payload parser file starts with a public section. Here you have to enter your the measuring ranges of the sensor your are using. The measuring ranges can be found on the model label of your sensor and in the data sheet of the sensor.

// PGU with NETRIS3
/**
 * The starting value of the pressure range.
 * @type {number}
 */
var PRESSURE_RANGE_START = 0 // bar

/**
 * The ending value of the pressure range.
 * @type {number}
 */
var PRESSURE_RANGE_END = 10 // bar

/**
 * The starting value of the device temperature range.
 * @type {number}
 */
var DEVICE_TEMPERATURE_RANGE_START = -40 // °C

/**
 * The ending value of the device temperature range.
 * @type {number}
 */
var DEVICE_TEMPERATURE_RANGE_END = 100 // °C

After the modification, you can use the index.js file on your network server.

Calling the parsing function

The parser exposes three functions to decode raw byte messages:

/**
 * "input": {
 *      "bytes": [1, 0, 0, 46, 151, 18, 83],
 *          "fPort": 1,
 *          "recvTime": "2023-11-11T13:37:00+02:00"
 *  }
 **/
const parser = require("index.js");
const output = parser.decodeUplink(input);
console.log(output);
/**
 *   "output": {
 *        "data": {
 *            "messageType": 1,
 *            "configurationId": 0,
 *            "measurement": {
 *                "channels": [
 *                    {
 *                        "channelId": 0,
 *                        "channelName": "pressure",
 *                        "value": 9.427
 *                    },
 *                    {
 *                        "channelId": 1,
 *                        "channelName": "device temperature",
 *                        "value": -18.09
 *                    }
 *                ]
 *            }
 *        }
 *    }
**/

For more information about parser using see the Legacy JavaScript Parser Usage

Release Notes

3.2.1

3.2.0

3.1.1

3.1.0

3.0.1

3.0.0

2.5.0

2.4.1

2.4.0

2.3.0

2.2.0

2.1.0

2.0.0

This site is open source. Improve this page.