Is there any documentation on payload functions?

(Mark Stanley) #1

I have seen some examples on payload functions.

Is there any guide on writing payload functions - what language are you using - what functions are available?

Step by step help for extracting data from the payload in node-red?
Advantage of Base64 encoding in MQTT?
Decrypting messages for dummies
TTN Console - Device authenticated but no payload displayed
(Morten Guldager) #2

It looks like javascript, but either it is not or some of the convenient libraries are missing. Would have loved to use ArrayBuffer to convert from bytes to float. See

The LIBRARY basement part 5
(Arjan) #3

It’s JavaScript (ECMAScript 5) indeed. For uplinks:

  • Decoder is a JavaScript function that accepts the payload as byte array and returns an object containing the decoded values. It gets passed:
    • First parameter, typically called bytes: the binary payload as an array of numbers. Each number is a byte, 0 to 255 in decimal notation, which is the same as 0x00 to 0xFF in hexadecimal notitation.
    • Second parameter, typically called port: the port number from 1 to 223.
  • Converter is a JavaScript function that accepts the object as returned by Decoder and returns an object containing the converted values.
  • Validator is a JavaScript function that validates the data as returned by Converter and returns a boolean value indicating the validity of the data.
  • :warning: Converter and Validator will be dropped in V3.

For downlinks:

  • Encoder is a JavaScript function that encodes the data queued for a Downlink messages and returns the converted values as an array of bytes.

Anything you send to console.log is shown in TTN Console during testing:


A good JavaScript resource is MDN Web Docs (formerly Mozilla Developer Network), and “mdn” is a great keyword for search engines: mdn array.

Also, you can use auto-completion in the developer tools of your browser. Just start by defining your payload with something like:

var bytes = [0xFF, 0x31, 0xF9, 0x12, 0x00, 0x31]

Or, to easily copy/paste a hexadecimal string such as 0xff31f9120031:

var bytes = 'ff31f9120031'.match(/(..)/g).map(b => parseInt(b, 16))

Next, typing bytes. will show you the supported functions and all:


Some examples:

Simple payload conversion
Decrypting messages for dummies
Decoding a float value in a payload function
Transmitting multiple values with one payload
Decoding node messages in ttn backend
Cayenne LPP format: analog data wrong
Virtual and real sensors on 1CH-gateway (ESP)?
Decoding byte payload
Getting "Decoder not valid: does not return an object"