Data payload

The data payload object represents a payload received from a device, for example a device with MQTT, HTTP, or LoRaWAN connectivity. The object allows accessing received data in binary form, as text, as a JSON object, and in other ways. This object is usually received as a parameter in certain scripts, such as MQTT, HTTP, or LoRaWAN data conversion scripts.

Properties

port (int, only available for LoRaWAN packets) The port property indicates the LoRaWAN port to which the device sent the payload. This property only has a value for payloads received through a LoRaWAN network. For other communication methods, the value is always zero.

Examples

This example shows the payload port in the log console.

env.log('Payload port: ', payload.port);

topic (string, only available for MQTT packets) The topic property indicates the MQTT topic to which the device sent the payload. This property only has a value for payloads received through MQTT. For other communication methods, the value is always an empty string.

Examples

This example shows the payload topic in the log console.

env.log('Payload topic: ', payload.topic);

buildResult (enum, only for downlinks)

The buildResult property allows indicating the result of building a payload for downlinks. This is typically used in the buildDownlink() function of the data processing script for LoRaWAN and MQTT. The possible values for this property are as follows:

• downlinkBuildResult.ok (0): .
• downlinkBuildResult.error (1): .
• downlinkBuildResult.unsupported (2): .

Examples

This example shows a code snippet indicating an error message during the creation of a downlink payload.

payload.buildResult = downlinkBuildResult.error;
payload.errorMessage = { en: "Invalid parameter", es: "Parámetro no válido" };

errorMessage (string or multi-language literal, only for downlinks) The errorMessage property allows indicating an error message during the construction of a payload for downlinks. This is typically used in the buildDownlink() function of the data processing script for LoRaWAN and MQTT, when using the value downlinkBuildResult.error in the buildResult property. The value assigned to this property can be a string, or a multi-language literal object.

Examples

This example shows a code snippet indicating an error message during the creation of a downlink payload.

payload.buildResult = downlinkBuildResult.error;
payload.errorMessage = { en: "Invalid parameter", es: "Parámetro no válido" };

requiresResponse (boolean, only for downlinks)

The requiresResponse property allows indicating whether the message being built requires a response from the device, or whether the command should be considered successfully completed as soon as it is sent.

• If the property has the value false (default value), the command will be considered sent as soon as the payload is sent to the MQTT broker (for MQTT devices), or the payload is queued at the LoRaWAN gateway (for LoRaWAN devices).
• If the property has the value true, the command will remain open until the device itself sends a response to the command.

The default value of this property is false.

Examples

This example shows a code snippet indicating that the payload does not require a response from the device.

payload.requiresResponse = false;

latitude (double, only for uplinks) The latitude property allows knowing the latitude of the device that sent data. This property is only available if the information provider was able to calculate the device's location through triangulation or an equivalent method.

Examples

This example shows a code snippet that displays the device's latitude.

env.log("Latitude: ", payload.latitude);

longitude (double, only for uplinks) The longitude property allows knowing the longitude of the device that sent data. This property is only available if the information provider was able to calculate the device's location through triangulation or an equivalent method.

Examples

This example shows a code snippet that displays the device's longitude.

env.log("Longitude: ", payload.longitude);

altitude (double, only for uplinks) The altitude property allows knowing the altitude of the device that sent data. This property is only available if the information provider was able to calculate the device's location through triangulation or an equivalent method.

Examples

This example shows a code snippet that displays the device's altitude.

env.log("Altitude: ", payload.altitude);

Methods

asBytes() The asBytes() method allows obtaining the payload content as a byte array. This is primarily used when the payload needs to be processed in binary form.

Example 1

This example shows the payload content as bytes, through the log console.

payload.asBytes().forEach(element => env.log(element));

asString() The asString() method allows obtaining the payload content as a string, converting the binary content to a string and assuming UTF-8 encoding. This is primarily used when the payload needs to be processed as text.

Example 1

This example shows the payload content as a string, through the log console.

env.log(payload.asString());

asJsonObject() The asJsonObject() method allows obtaining the payload content as an object, assuming the payload is text encoded in JSON format. This is primarily used when the payload needs to be processed as JSON text.

Example 1

This example shows the payload content as a JSON object, through the log console.

env.log(payload.asJsonObject());

asParsedObject() The asParsedObject() method allows obtaining the parsed version of the payload, as sent to the platform. Some communication platforms, such as Actility and The Things Stack, are capable of sending a processed version of the payload information, in addition to the binary data. This method allows accessing the information sent by these platforms directly. Note that the result may be null if no processed data was received.

Example 1

This example shows the payload content processed by the communication platform, through the log console.

env.log(payload.asParsedObject());

setAsBytes(bytesContent) The setAsBytes() method allows setting the payload content as a byte array. This method is normally used when creating downlinks.

Parameters

• bytesContent (array of bytes): new payload content, expressed as a byte array.

Example 1

This example shows how to set the payload as a five-byte array.

payload.setAsBytes([9, 8, 7, 6, 5]);

setAsString(stringContent) The setAsString() method allows setting the payload content as text. This method is normally used when creating downlinks.

Parameters

• stringContent (string): new payload content, expressed as text.

Example 1

This example shows how to set the payload as text.

payload.setAsString("Some text");

setAsJsonObject(objectContent) The setAsJsonObject() method allows setting the payload content as an object, which will be converted to its JSON format representation. This method is normally used when creating downlinks.

Parameters

• objectContent (object): new payload content, expressed as an object.

Example 1

This example shows how to set the payload as an object.

payload.setAsJsonObject({ on: true, dimLevel: 65 });

____________________________________________________________________________________________________________________________

Network Signal

payload.rssi.quality

Measures the quality of the signal with which the message is received. It is a percentage and its value can range between 0 and 100.

Javascript
			var rssiQuality = payload.rssi.quality;
			env.log("Quality:", rssiQuality);

Ejemplo:
Json
          "rssi":
                  {
                  "quality": 87
                    }

Signal Strength

payload.rssi.strength

Is the signal strength. Measures the power, generally in decibels. It is better when the number is lower.

Javascript
			var rssiStrength = payload.rssi.strength;
			env.log("Strength:", rssiStrength);

Ejemplo:
Json
        "rssi": {
  				  "strength": 8
 				 }

Signal Type

payload.rssi.type

References the communication method type used by the device to send the message. For example: LoRaWAN, NbIoT, LTE, etc.

Javascript
			var rssiType = payload.rssi.type;
			env.log("Type:", rssiType);

Json
Ejemplo:
		"rssi":
				{
  				  "type": "lora"
				}

PORT

payload.port

The logical port used by the device that serves to identify the data type or format.

Javascript
			var port = payload.port;
			env.log("Port:", port);

Json

			"port": 1

TOPIC

payload.topic

The channel through which the message was received. Useful for architectures with multiple routes or MQTT type.

javascript

			var topic = payload.topic;
			env.log("Topic:", topic);

Json
           "topic": "uplink/temperature"

LATITUDE

payload.latitude

Indicates the north/south position from where the message was sent.

var latitude = payload.latitude; env.log("Latitude:", latitude);

javascript

			var latitude = payload.latitude;
			env.log("Latitude:", latitude);

Json
			"latitude": 19.4326

LONGITUDE

payload.longitude

Indicates the east/west position from where the message originated.

Javascript
		     var longitude = payload.longitude;
			 env.log("Longitude:", longitude);

 Ejemplo:
			 "longitude": -99.1332

Altitude

payload.altitude

Represents the height in meters above sea level where the device that made the transmission is located.

javascript

			var altitude = payload.altitude;
			env.log("Altitude:", altitude);

Json
	"altitude": 2250