NAS Payload Codec

Supported devices

• cm30xx: CM3011, CM3013, CM3021, CM3022, CM3030, CM3040, CM3061, CM3080, CM3120, CM3130 with 1.3.x and 2.3.x firmwares. Note: 1.3.x and 2.3.x protocol is identical, major version number signifies used radio chipset.
• ul20xx: UL2002, UL2003, UL2014, UL2020, UL2021, UL2023, UL2024, UL2030, UL2033, UL2034, UL2053 with 1.0.x and 1.1.x firmwares. Note: does not support legacy_status_packet.
• um30xx: UM3070, UM3081, UM3090, UM3100, UM3110, UM3140 with 4.0.x firmware.
• im30xx: IM3060, IM3100

Live decoding in browser

UL20xx 1.1.x live decoder

UL20xx 1.0.x live decoder

CM30xx 1.3.x / 2.3.x live decoder

UM30xx live decoder

IM30xx 0.9.x / 0.10.x live decoder

Or download respective .html file in generated folder.

Live encoding in browser

UL20xx 1.1.x live encoder

Using on TTN (or Chirpstack)

• open minified .js file for appropriate device from generated folder.
• click on file (like /generated/ul20xx_1_0_x_decoder.min.js)
• click on Raw
• copy everything
• in e.g. TTN Select your LCU Application -> then Payload Formatters -> Uplink -> Formatter type: Custom Javascript Formatter and paste the code there.
• repeat it for Downlink aswell

Supported platforms

• Chirpstack (how to use chirpstack decoder: https://github.com/nasys/nas-codecs/blob/main/NAS%20Codec%20ChirpstackInstallation%20Guide.md)
• The Things Network (add as Custom Javascript Formatter to both Uplink and Downlink)
• easily adoptable to anything that uses javascript
• at least useful starting point for porting to other platforms / languages TTN has maximum code limit of 40960 characters. No one thought that anyone needs that much, but yep, some overengineering and there you go. If you see this error just use the minified version, e.g. generated/some_decoder.min.js.

Codec Overview

• Written in ES5 javascript (ES5 required by e.g. chirpstack and TTN).
• decodeRaw() output raw JSON objects. On UL20xx each data-point contains value key plus optionally raw, unit etc. On CM30xx and UM30xx key of data-point contains unit (e.g. accumulated_volume__m3) and sometimes __formatted field.
• Raw output can be easily re-formatted or used programmatically. Default convertToFormatted() converts raw to compact format where value and unit are concatenated and serves as an example.
• Serves as annex for respective Payload Description documents.

Implementation Reference

To understand how to decode a certain packet, one can study generated/xxxxxx_x_x_x_decoder.js file. Start from decodeRaw() at the end of the file and move upwards. The actual source is in src/xxxxxx_decoder.js but it has several processing steps applied to it.

Structure

Structure is based on TTN.

data - the decoded output.

errors - payload parsing errors, field ommited if empty.

warnings - alerts from the device, field ommited if empty.

{
  "data": {},
  "errors": [],
  "warnings": []
}

Decoding output Example

{
  "data": {
    "packet_type": "status_packet",
    "device_unix_epoch": "2020-01-14T14:49:03.000Z",
    "status": {
      "dali_error_external": "false",
      "dali_connection_error": "false",
      "ldr_on": "false",
      "dig_on": "false",
      "hardware_error": "false",
      "internal_relay_closed": "false"
      "open_drain_output_on": "false",
    },
    "downlink_rssi": "-75 dBm",
    "downlink_snr": "4 dB",
    "mcu_temperature": "21 °C",
    "analog_interfaces": {
      "voltage_alert_in_24h": "false",
      "lamp_error_alert_in_24h": "false",
      "power_alert_in_24h": "false",
      "power_factor_alert_in_24h": "false"
    },
    "ldr_value": "174",
    "profiles": [
      {
        "profile_id": "5",
        "profile_version": "5",
        "profile_override": "none",
        "dali_address_short": "dali_single_5",
        "days_active": "holiday,mon,tue,wed,thu,fri,sat,sun",
        "dimming_level": "50 %"
      },
      {
        "profile_id": "3",
        "profile_version": "3",
        "profile_override": "none",
        "dali_address_short": "dali_single_3",
        "days_active": "holiday,mon,tue,wed,thu,fri,sat,sun",
        "dimming_level": "0 %"
      }
    ]
  }
}

Reporting errors

Please report issues in Github Issues page.

Getting started

First test the codec Live - See Live decoding example above.

For testing on your platform download respective file from generated/ folder and modify/replace the entry function to call decodeRaw(). Inside that function the output can also be reformatted however is needed.

Since new features are added occasionally and bugs fixed, the library will be updated. Re-generating codec files with custom entry function can be achieved by modifying default entry functions in config/ folder and then generating the js files again (see Rebuild below).

Installation

Only needed if one wants to regenerate the output or run tests etc. Node must be installed. To install dependencies: npm install

Build

npm run build_cm30xx_2_3_x && npm run build_cm30xx_2_3_x_html npm run build_ul20xx_1_0_x && npm run build_ul20xx_1_0_x_html npm run build_ul20xx_1_1_x && npm run build_ul20xx_1_1_x_html npm run build_ul20xx_1_1_x_ttn_downlink && npm run build_ul20xx_1_1_x_ttn_uplink npm run build_ul20xx_1_1_x_encoder && npm run build_ul20xx_1_1_x_encoder_html

npm run build_um30xx_4_0_x && npm run build_um30xx_4_0_x_html

npm run build_im30xx_0_9_x && npm run build_im30xx_0_9_x_html

Running tests:

npm test If src folder has been modified, run at least first half of the build command (generating html not needed). npm run build_cm30xx_2_3_x && npm run build_um30xx_4_0_x && npm run build_ul20xx_1_0_x && npm run build_ul20xx_1_1_x && npm run build_ul20xx_1_1_x_encoder && npm run build_im30xx_0_9_x && npm test

Coverage overlay in VS Code

install VS Code 'Jest' extension Cmd+P Command pallete: Jest: Start All Runners Cmd+P Command pallete: Jest: Toggle Coverage

Third party software

UM30xx decoder uses tiny (TMBUS)[https://dev-lab.github.io/tmbus/] library which is licensed under (Apache License)[https://dev-lab.github.io/tmbus/LICENSE].