Skip to content
The Things Stack documentation home
Getting Started Concepts Cloud Enterprise Integrations API Hardware
Getting Started Concepts
Cloud Enterprise
Integrations API Hardware
Get The Things Stack

    Recent searches

      Popular pages

      • Getting Started
      • Adding Gateways
      • Adding Devices
      • Payload Formatters
      • Webhooks
      • Authentication

      No results for “”.

      • Check the spelling, or try fewer or more general words.
      • Ask the community on The Things Network Forum
      • Contact support
      ↑↓ to navigate ↵ to open Esc to close

      Integrations

      • Overview
      • Adding Applications
      • Data Formats
      • Payload Formatters
        • Creating Payload Formatters
        • CayenneLPP
        • Device Repository
        • JavaScript
          • Uplink
          • Downlink
      • Webhooks
      • Storage Integration
      • Integrate with popular IoT platforms
      • Other integrations
      • Application Packages
      • Examples

      Uplink

      Updated 15 July 2025 Edit on GitHub
      Copy page
      • View as MarkdownThis page as plain text
      • Open in ChatGPTAsk questions about this page
      • Open in ClaudeAsk questions about this page

      The JavaScript decodeUplink() function is called when a data uplink message is received from a device. This function decodes the binary payload received from the end device to a human-readable JSON object that gets send upstream to the application. If present, the normalizeUplink() function is called to normalize the decoded payload in a common data structure.

      The decoder function takes an input object and returns an output object:

      function decodeUplink(input) {
        // input has the following structure:
        // {
        //   "bytes": [1, 2, 3], // FRMPayload (byte array)
        //   "fPort": 1
        //   "recvTime": "Thu Jan 16 2025 17:29:37 GMT+0200 (Eastern European Standard Time)" // receivedAt (Date object)
        // }
        return {
          data: {
            bytes: input.bytes,
          },
          warnings: ["warning 1", "warning 2"], // optional
          errors: ["error 1", "error 2"], // optional (if set, the decoding failed)
        };
      }
      

      The decoder function’s output shown above is incorporated in the as.up.data.forward event, where the data.uplink_message object contains:

      {
        "f_port": 1,
        "frm_payload": "AQID",
        "decoded_payload": {
          "bytes": [1, 2, 3]
        }
      }
      

      Uplink payload is transmitted as binary payload by the end device. The Things Stack shows this binary payload in the frm_payload field (Base64 encoded). The result of the decodeUplink() function is contained in the decoded_payload field.

      If an error is present in errors, the payload is invalid. If the decoder or the normalizer return an error, applications still receive the message but only the binary payload in frm_payload. Any warnings in warnings are informative.

      Note:

      You can test your uplink decoder, as well as simulate uplinks from The Things Stack Console.

      Normalized Payload

      The uplink decoder can return any data structure. This provides full flexibility: a decoder can return any measurement in any unit as well as any additional information.

      However, developers building applications that combine data from various device types may find it difficult to work with different data structures.

      This is what the normalization step is for: the decoded payload gets normalized to a data structure that is common for all device types. Normalized payload is complementary to decoded payload: some measurements or some information may not fit in the normalized payload data structure. Therefore, some application may use normalized payload while others use decoded payload carrying device specific information.

      The normalizer function takes the output from the decoder function and returns an output object:

      function normalizeUplink(input) {
        // input has the following structure:
        // {
        //   "data": {
        //     "temperature": 50, // Fahrenheit
        //     "windSpeed": 17.5 // knots
        //   }
        // }
        return {
          data: {
            air: {
              temperature: ((input.data.temperature - 32) * 5) / 9, // Fahrenheit to Celsius
            },
            wind: {
              speed: input.data.windSpeed * 0.5144, // knots to m/s
            },
          },
          warnings: ["warning 1", "warning 2"], // optional
          errors: ["error 1", "error 2"], // optional (if set, the normalization failed)
        };
      }
      

      The normalizer function’s output shown above is incorporated in the as.up.data.forward event, where the data.uplink_message object contains:

      {
        "decoded_payload": {
          "temperature": 50,
          "windSpeed": 17.5
        },
        "normalized_payload": [
          {
            "air": {
              "temperature": 10
            },
            "wind": {
              "speed": 9.002
            }
          }
        ]
      }
      

      The Application Server also publishes an event for each returned normalized payload, in the as.up.normalized.forward event, where the data.uplink_normalized object contains:

      {
        "normalized_payload": {
          "air": {
            "temperature": 10
          },
          "wind": {
            "speed": 9.002
          }
        }
      }
      

      Note:

      The uplink message data contains an array of normalized payload measurements (normalized_payload is an array) while the normalized uplink data contains a single normalized payload measurement. See below why and how this is useful.

      Normalized Payload Schema

      The normalized payload schema is continuously being extended to support more fields. You can find the latest JSON Schema definition in the LoRaWAN Device Repository.

      {
        "time": "2022-08-29T13:50:15Z", // Timestamp (RFC 3339)
        "battery": 3.3, // Battery level (V)
        "soil": {
          "depth": 22,        // Depth from the surface (cm): [0..)
          "moisture": 55,     // Soil moisture (%): [0..100]
          "temperature": 8.1, // Soil temperature (Celsius): [-273.15..)
          "ec": 125,          // Soil electrical conductivity (dS/m): [0..621]
          "pH": 7,            // Soil pH level: [0..14]
          "n": 1234,          // Concentration of Nitrogen in the soil (ppm): [0..1000000]
          "p": 5678,          // Concentration of Phosphorus in the soil (ppm): [0..1000000]
          "k": 9012           // Concentration of Potassium in the soil (ppm): [0..1000000]
        },
        "air": {
          "location": "outdoor",    // Specifies whether the measurement was taken indoors or outdoors: indoor, outdoor
          "pressure": 1032,         // Atmospheric pressure (hPa): [900..1100]
          "relativeHumidity": 43.9, // Relative humidity (%): [0..100]
          "temperature": 21.5,      // Temperature (Celsius): [-273.15..)
          "co2": 5678,              // Concentration of CO2 in the air (ppm): [0..1000000]
          "lightIntensity": 400     // Light intensity (lux): [0..)
        },
        "wind": {
          "direction": 321, // Direction (degrees): [0..360)
          "speed": 5.2      // Speed (m/s): [0..)
        },
        "rain": {
          "intensity": 25,   // Rainfall intensity (mm/hour): [0..)
          "cumulative": 500  // Cumulative rainfall (mm): [0..)
        },
        "water": {
          "leak": "true", // Leak detected (boolean)
          "temperature": {
            "min": 13.5,      // Minimum temperature (Celsius): [-273.15..)
            "max": 18.0,      // Maxinmum temperature (Celsius): [-273.15..)
            "avg": 15.1,      // Average temperature (Celsius): [-273.15..)
            "current": 15.6   // Current temperature (Celsius): [-273.15..)
          },
        },
        "metering": {
          "water": {
            "total": 125.6, // Total volume (L): [0..)
          }
        },
        "action": {
          "motion": {
            "detected": true, // Motion detected (boolean)
            "count": 55,      // Number of motion events (count): [0..)
          },
          "contactState": "closed" // State of a contact sensor: open, closed
        },
        "position": {
          "latitude": 52.5,  // Horizontal distance from the equator (degrees): [-90..90]
          "longitude": 4.889 // Vertical distance from prime meridian (degrees): [-180..180]
        }
      }
      

      Advanced: Return Multiple Measurements

      Multiple measurements can be encoded by the end device in a single LoRaWAN® uplink message. This is a good practice as it is more battery efficient. Therefore, the uplink decoder may find multiple measurements from the same sensor. The normalizer function can therefore return an array of measurements, as an alternative to a single measurement:

      function normalizeUplink(input) {
        // input has the following structure:
        // {
        //   "data": {
        //     "readings": [
        //       { "temperature": 51.4 },
        //       { "temperature": 50.1 },
        //       { "temperature": 56.8 }
        //     ]
        //   }
        // }
        var data = [];
        for (var i = 0; i < input.data.readings.length; i++) {
          data.push({
            air: {
              temperature: ((input.data.readings[i].temperature - 32) * 5) / 9,
            },
          });
        }
        return {
          data: data, // this is now an array: [ { air: { temperature: ... } }, ... ]
        };
      }
      

      When the normalizer function returns an array of measurements, Application Server publishes a normalized uplink event for each measurement, while there is still one uplink message event.

      Uplink Example: The Things Node

      Here is an example decodeUplink() function from The Things Node:

      function decodeUplink(input) {
        var data = {};
        var events = {
          1: "setup",
          2: "interval",
          3: "motion",
          4: "button",
        };
        data.recvTime = input.recvTime.toString();
        data.event = events[input.fPort];
        data.battery = (input.bytes[0] << 8) + input.bytes[1];
        data.light = (input.bytes[2] << 8) + input.bytes[3];
        data.temperature =
          (((input.bytes[4] & 0x80 ? input.bytes[4] - 0x100 : input.bytes[4]) << 8) +
            input.bytes[5]) /
          100;
        var warnings = [];
        if (data.temperature < -10) {
          warnings.push("it's cold");
        }
        return {
          data: data,
          warnings: warnings,
        };
      }
      
      function normalizeUplink(input) {
        return {
          data: {
            air: {
              temperature: input.data.temperature,
            },
          },
        };
      }
      

      For example, the end device observed an event and performed some measurements. The end device transmitted the following binary payload: 0C B2 04 80 F7 AE (hex encoded) on FPort 4. The Base64 equivalent of that binary payload is DLIEgPeu and the JavaScript byte array is [ 12, 178, 4, 128, 247, 174 ]. This is all the same, just a different representation.

      The uplink decoder gets the JavaScript byte array of the binary payload, the FPort and the time of receipt (recvTime) as input. The Things Stack sets frm_payload to the Base64 representation of the binary payload, and decoded_payload to the output data of the uplink decoder. If there are warnings, they are set in decoded_payload_warnings.

      The data.uplink_message object of the as.up.data.forward event will contain:

      {
        "uplink_message": {
          "f_port": 4,
          "frm_payload": "DLIEgPeu",
          "decoded_payload": {
            "battery": 3250,
            "event": "setup",
            "light": 1152,
            "recvTime": "Tue Jan 21 2025 17:56:54 GMT+0100 (CET)",
            "temperature": -21.3
          },
          "decoded_payload_warnings": ["it's cold"],
          "normalized_payload": [
            {
              "air": {
                "temperature": -21.3
              }
            }
          ]
        }
      }
      

      Since there is normalized_payload, there will also be a as.up.normalized.forward event published:

      {
        "uplink_normalized": {
          "f_port": 4,
          "frm_payload": "DLIEgPeu",
          "normalized_payload": {
            "air": {
              "temperature": -21.3
            }
          }
        }
      }
      
      Testing an uplink decoder
      ← JavaScript Downlink →

      On this page

      • Normalized Payload
      • Uplink Example: The Things Node

      Sections

      Getting Started

      Concepts

      Cloud

      Enterprise

      Integrations

      API

      Hardware

      Sitemap

      View our Sitemap

      Contributing

      GitHub

      About Us

      The Things Industries

      Privacy Policy

      Cookie settings

      Cookie Settings

      We use cookies to enhance your experience, analyze site traffic and deliver personalized content. Read our Privacy Policy.

      Cookie categories