Parsers to decode data from devices and encode data to devices. Build upon WIKA's javascript parser library

Device Parsers Guide

This guide explains how to use the device parser UI to configure, encode, and decode payloads for your device, no coding required.

Supported Parsers

  • NETRIS2 (channels fixed to 4 to 20 mA, cannot change min, max, or unit)

Note: Support for additional device parsers is coming soon.

Features

  • Tabbed Interface:
    At the top of the page, you will find tabs for "Encoding" and "Decoding". Click a tab to switch between configuring downlinks and decoding uplinks.
  • Link Sharing:
    All your configuration data is stored in the page URL. You can bookmark or share the link to save or send your current settings and form state to others. This makes collaboration and support much easier.

Parser Configuration

Before you start encoding or decoding, you may need to configure the parser to match your device's measurement ranges and units.
Depending on your device and where it is used, the available ranges, units, and channel count may differ.
You can set these options in the parser configuration section at the top of the page.

Note: For NETRIS2, the measurement ranges (min, max, unit) are fixed to 4 to 20 mA and cannot be changed.

Settings

  • Encoder Settings:
    At the top of the encoding form, you can set general device parameters such as the Configuration ID, which is used to match configuration commands and responses, and the LoRaWAN Spreading Factor, which affects range and data rate.

Encoding

  • Configuration Form:
    The main area of the "Encoding" tab is a form split into logical sections:
    • Quick Actions: Buttons for factory reset and battery indicator reset.
    • Encoder Settings: General device settings as described above.
    • Main Configuration: Set measurement rates and publication factors for both normal and alarm conditions. The UI will show you the resulting transmission interval.
    • Channel Tabs:
      The UI provides a section or tab for each available channel. The number of channels shown depends on the device you are configuring. Some devices may have two channels, while others may have more.
      The available options and fields for each channel may also vary depending on the device. For each channel, you can:
      • Enable or disable the channel.
      • Set thresholds for alarms, including low or high thresholds, with or without delay.
      • Configure dead band, slope alarms (rising or falling), measurement offset, and start-up time.
      • All fields have tooltips and hints to guide you, including valid ranges and units.
    • Field Validation: The UI checks your input and provides immediate feedback if a value is out of range or a required field is missing.
    • Tooltips and Visuals: Many fields include tooltips with explanations and images to help you understand what each setting does.
  • Encode Downlink:
    After filling out the form, click the "Encode Downlink" button. The encoded frame or frames will appear in a results panel, ready to copy or download.
  • What you can do:
    • Configure all device settings visually, with immediate feedback and help.
    • Save and share your configuration via URL.
    • Instantly generate valid downlink frames for your device.
    • Use quick actions for common device resets.
  • Encoding Configuration May Vary:
    The available encoding configuration options and fields may differ depending on the device you are working with. Some devices offer more channels or different alarm and measurement settings. The encode page will automatically adapt to show only the relevant options for your selected device.

Decoding

  • Decode Uplink:
    Switch to the "Decoding" tab to access the uplink decoder.
    • Paste your received payload, either in hex or base64, into the input field.
    • The UI will automatically decode and display the interpreted data in a readable format.
    • Decoded values are shown with units and field names for clarity.
    • Any errors or warnings are displayed below the result.
  • What you can do:
    • Instantly decode uplink payloads from your device.
    • See all decoded values, alarms, and status fields with clear labels and units.
    • Share the decoded result with support or colleagues.

Download and Usage

  • Download Encoded Frames:
    The results panel in the encoding tab allows you to copy the encoded frames to your clipboard or download them as a file.
  • Download the Parser with Your Settings:
    When you download the parser script from the encode page, it automatically includes all your current settings, such as channel configuration, rounding decimals, and other options. This means that after you have verified your configuration and ensured the encoded frames are correct, you can download a parser that is ready to use with your device and settings. No further adjustments are needed after download.
  • Always Up to Date:
    The downloadable parser is always kept in sync with the latest release of the JavaScript parsers. You can be confident that you are using the most recent and reliable version.
  • Bookmarking and Sharing:
    Since all configuration data is stored in the URL, you can bookmark your current configuration or share it with colleagues or support for troubleshooting.

LoRa Alliance Payload Codec API Compliance

The downloaded parser is fully compliant with the LoRa Alliance Payload Codec API spec. However, some network server or gateway providers may not fully adhere to the LoRa Alliance Payload Codec API specification. In such cases, you might need to add a small code snippet at the end of the downloaded file to adapt it for your specific environment.

Usage in a Network Server or Gateway

Once you have downloaded the parser with your verified settings:

  1. Upload or paste the parser script into your network server or gateway's custom decoder or encoder section.
  2. No further configuration is needed, as your settings are already included.
  3. If your network server requires a specific function signature or export, you may need to add a small code snippet at the end of the file.

Example workflow:

  • Configure and verify your settings in the encode page.
  • Download the parser.
  • Upload the parser to your network server.
  • If needed, add a small code snippet for compatibility. See below for examples.

If you need more advanced features or want to integrate the parser into your own application, please refer directly to the parsers repository and the server and web examples. These examples are based on the official @w2a-iiot/parsers npm package.