DIY Decoder

DIY Decoders is a Things Creator feature that allows you to provide your own decoder script to decode messages from your devices on the KPN Things platform. To be able to create your own decoder, you'll first need to have access to Things Creator. If you don't see the Things Creator option in the top-level menu, please request Things Creator access from the administrator of your organisation.

DIY decoders are supported for your own device types that you've created in Things Creator. Once you've created a custom device type, you can create a new decoder for it and specify the decoding script that should be used to decode device messages. The decoding script should be written in JavaScript. See DIY decoder scripts for a more detailed description and some example scripts.

How it works

To be able to create a DIY decoder, you will need a DIY decoder supported device type. This may be achieved by creating a custom device type for your device(s). See how to add a new device type for more information.

A step by step walk-through is presented in the next section which guides through the creation of a DIY decoder.

Step by step guide

In this section a DIY decoder with a script is created step by step. Important sections on the images are indicated with either a red square or a red number.

Step 1. Overview page

The above image presents the overview page of the KPN Things portal. DIY decoders can be created in the Things Creator section of the portal.

Step 2. Creator page

On the Things Creator page, clicking the All Decoders menu item in the side bar will bring us to the page where we can initiate the creation of a new DIY decoder.

Step 3. Add decoder button

Clicking the Add new Decoder button brings us to the DIY decoder creation page.

Step 4. Add decoder form

The DIY decoder creation page expects a few details to be filled in:

1. Name - the name of the decoder (required)

2. Description - description describing the purpose of the decoder (optional)

3. Device Type - the device type that this decoder will be linked to (required)

   1. Your custom device types will also appear in the drop-down list. See how to add a new device type for more information.
4. Buttons - to either submit the new DIY decoder or to cancel the process.

Step 5. Created decoder details

The decoder overview screen will be presented when a DIY decoder has been created. A few things are visible here:

1. The details of the decoder that we have just created.

2. The button to create the script for the decoder.

3. The edit button to edit the decoder details.

4. The delete button that deletes this decoder. A pop-up asks for a confirmation first.

Step 6. New decoder script

When creating a script for a DIY decoder, the page with a script editor and tester is presented.

1. Script Editor

The script editor automatically contains a working default script for the supported payload data, for LoRa - Hex in this case. The script may of course be customized or fully replaced, but it has to adhere to the script code rules.

Initially, we do not provide a rich code editor in the KPN Things portal. We suggest you write the code snippet in the editor of your choice and paste the content in the script field of the DIY decoder edit page in KPN Things portal.

For more default scripts for various payload types, please see this page.

1. Script Tester

The script tester tests the script from the editor in combination with the provided message data provided in the tester window. This is done in an isolated environment. The result of the test execution is shown in the Output window and script logs are displayed in the Log window. Errors that may occur, will be displayed in both Output and Log windows.

It is safe to trial-and-error within the tester as it does not touch or involve anything from outside of the isolated test environment.

The script tester provides a few options:

• Payload data - the type of payload data that the device type supports. The drop-down list will contain every supported payload data to choose from.

• Message detail - whether only the payload or the entire uplink message should be displayed in the text field below. The message data is editable.

• Test button - executes the test with the script that is currently present in the editor and the message data. The tester always uses the full uplink message data, no matter which message detail is selected.

• Output window - presents the result of the test execution.

• Log window - custom script logs or various error messages will appear in this window.Comment

Errors

Output window:

Script errors - when an error is thrown in the script itself. A warning toast will also pop-up at the top center of the page stating that the script did not execute successfully.

JavaScript errors (ReferenceError, SyntaxError, TypeError…) - when a JavaScript error occurs. The accompanying error message is also present for clarity what went wrong.

Log window:

Output is not valid SenML - when the output contains invalid SenML records. Output will still be displayed in the output window.

SenML processing errors - when a SenML specific error occurs.

Step 7. Decoder ready

Now the decoder creation process is finished. After activating your DIY decoder in a flow, all messages from your devices that are part of that flow and have a device type supported by the DIY decoder, are decoded by your own DIY Decoder and sent to all destinations configured for that flow.