The Payload Parser was created to handle the raw payload sent by the devices in order to extract the measured variables. In some cases, the devices send a string with the representation of  HEX/Binary or others formats, and it doesn't make sense for humans. 

Another use for Payload Parser is to make you able to handle the payload in real-time, allowing the conversion of a value to a desired unit. For example, if your data contains a temperature in Fahrenheit, you can use the parser to convert it into Celsius before inserting the data into the Bucket.

The Payload Parser does not take the place of TagoIO Analysis, it has a simple JavaScript engine which was coded by TagoIO to be easy, light and free. Therefore, the Parser has some limitations compared to the Analysis.

Features
Payload Parser
Analysis
Code size limit
100kb
5MB
Language
Simple JavaScript syntax
Full JavaScript and others
Async
No
Yes
Sync
Yes
Yes
Allows Custom Functions
Yes
Yes
Allows external integration
No
Yes
Allows requires/imports
No
Yes
Console Log or Context
No
Yes
Timeout
1,000 ms
30,000 ms
Needs Action to trigger it
No
Yes
Cost of the service
Free
Check out /pricing

As you can see, there is a lot of difference between both and the code wrote for the Analysis is incompatible with the one for Parser. 

How is the Payload Parser triggered?  

Data Flow from Device to Bucket

The payload parser is automatically triggered every time the device sends data to TagoIO (no need to setup anything). Your payload parser is the first step that gets triggered before saving data in the bucket, so if your code has an error it will be returned directly to the device HTTP post response. 

Using Context

Before we show some examples, you  need to understand how context works.

When you start writing your Tago Payload Parser, you can use certain globals variables in your code. Think of these global variables as variables that you can access anywhere without actually creating them, like the module keyword or the process keyword in Node.js. 

These global variables can vary from simple objects to complex functions or arrays. To see a list of the global variables available, you can always check the Payload Parser tab in the device details. 

The most important variable is the payload variable. This variable is always available anywhere on the code. It is an array with objects in the TagoIO format and with it you can edit, remove or even add more payload variables as you wish.

Our team can always add more global variables, depending on your needs (let us know).

A parse example

For this example, let's connect a toaster to Tago.

A toaster could send data to TagoIO when your bread is toasted in the following format:

The value above could represent: XX YYY ZZ.  Where:

ValuesRepresentation
XX00 - Interrupted, 01 - Successful
YYYTemperature in Fahrenheit
ZZError code or 00 - No error

That value is good enough for machine or engineers, but for humans, it doesn't mean anything and also it's not optimized for the Tago Dashboard. Therefore, we need to parse this payload.

Let's code the Payload Parser to transform that payload into real variables. First, click on your Device and go to the Payload Parser tab.

On the Payload Parser tab you will see the code editor. Then, you can write the following code:

Save, and you are ready. Now, every time the toaster sends those variables, the parser will transform it in real variables, and you can use them to build Dashboard, Analysis, or Action.

Payload Parser is a free feature, you can use it right away.

Learn how to build your own parser function.