Cayenne LPP 2.0


#1

Hi everyone !

Please find below an extract with some addition to our Low Power Payload format starting on section 3.3.
Feel free to share any comment or contribute, and enjoy !

Eric

3. Overview

The Cayenne Low Power Payload (LPP) provides a convenient and easy way to send data over LPWAN networks such as LoRaWAN. The Cayenne LPP is compliant with the payload size restriction, which can be lowered down to 11 bytes, and allows the device to send multiple sensor data at a time or splitted into several frames.

3.1. Data Channel

The Data Channel uniquely identifies each sensor or actuator within a device. Acceptable range is from 0 to 64. The device developer is responsible to assign a unique channel for each of the device’s sensor and actuator and conform to it across the device life cycle.

3.2. Data Types

Data Types are based on the IPSO Alliance Smart Objects Guidelines, which identifies each data type with an “Object ID”. However, as shown below, a conversion is made to fit the Object ID into a single byte.

LPP_DATA_TYPE = IPSO_OBJECT_ID - 3200

Each data type can use 1 or more bytes to send the data according to the following table.

Type IPSO LPP Hex Data Size Data Resolution per bit
Digital Input 3200 0 0 1 1
Digital Output 3201 1 1 1 1
Analog Input 3202 2 2 2 0.01 Signed
Analog Output 3203 3 3 2 0.01 Signed
Illuminance Sensor 3301 101 65 2 1 Lux Unsigned MSB
Presence Sensor 3302 102 66 1 1
Temperature Sensor 3303 103 67 2 0.1 °C Signed MSB
Humidity Sensor 3304 104 68 1 0.5 % Unsigned
Accelerometer 3313 113 71 6 0.001 G Signed MSB per axis
Barometer 3315 115 73 2 0.1 hPa Unsigned MSB
Gyrometer 3334 134 86 6 0.01 °/s Signed MSB per axis
GPS Location 3336 136 88 9 Latitude : 0.0001 ° Signed MSB Longitude : 0.0001 ° Signed MSB Altitude : 0.01 meter Signed MSB

3.3. Frame Ports

Cayenne LPP uses the LoRaWAN Frame Ports to identify and define different payload format, for different behavior. Following table provides all ports used and the format associated - defined in section 4 - as well as the possible directions, TX (Uplink) and/or RX (Downlink).

Frame Port Payload Format TX RX
1 Dynamic Sensor Payload
2 Packed Sensor Payload
3 Full scale GPS Payload
4 Reserved
5 Reserved
6 Reserved
7 Reserved
8 Reserved
9 Reserved
10 Actuator Commands
11 Device Period Configuration
13 Sensor Period Configuration
14 Sensor Enable Configuration
15 Reserved
16 Reserved
17 Reserved
18 Reserved
19 Reserved
20-99 Reserved
100-199 History Sensor Payload
200-255 Reserved

4. Payload Formats

4.1. Dynamic Sensor Payload

The Dynamic Sensor Payload is the best option when the developer needs a flexible payload format, to send some sensors in one frame, some others in another frame, or when he has multiple times the same type of sensor.

With the Dynamic Sensor Payload, each data must be prefixed with two bytes :

  • Data Channel : Uniquely identifies each sensor in the device across frames, eg. “indoor sensor”

  • Data Type : Identifies the data type in the frame, eg. “temperature”.

The data itself must conform to the type data size and precision as defined in the Data Types section.

1 Byte 1 Byte N Bytes 1 Byte 1 Byte M Bytes ...
Data1 Ch. Data1 Type Data1 Data2 Ch. Data2 Type Data2 ...

4.1.1. Device with 2 temperature sensors

Payload (Hex) 03 67 01 10 05 67 00 FF
Data Channel Type Value
03 ⇒ 3 67 ⇒ Temperature 0110 = 272 ⇒ 27.2°C
05 ⇒ 5 67 ⇒ Temperature 00FF = 255 ⇒ 25.5°C

4.1.2. Device with temperature and acceleration sensors

Frame N

Payload (Hex) 01 67 FF D7
Data Channel Type Value
01 ⇒ 1 67 ⇒ Temperature FFD7 = - 41 ⇒ - 4.1°C

Frame N+1

Payload (Hex) 06 71 04 D2 FB 2E 00 00
Data Channel Type Value
06 ⇒ 6 71 ⇒ Accelerometer X : 04D2 = + 1234 ⇒ + 1.234G Y : FB2E = - 1234 ⇒ - 1.234G Z : 0000 = 0 ⇒ 0G

4.1.3. Device with GPS

Payload (Hex) 01 88 06 76 5f f2 96 0a 00 03 e8
Data Channel Type Value
01 ⇒ 1 88 ⇒ GPS Latitude: 06765f ⇒ 42.3519 Longitude: F2960a ⇒ -87.9094 Altitude: 0003E8 ⇒ 10 meters

4.2. Packed Sensor Payload

For devices with a limited set of sensors data that are always sent, it is possible to remove the channel byte prefix. In such case, the order of the various data must remain the same across the device lifecycle. Channels will be automatically assigned from 0 and incremented with each data.The type byte remains mandatory, as used in the Dynamic Sensor Payload above.

1 Byte N Bytes 1 Byte M Bytes ...
Data1 Type Data1 Data2 Type Data2 ...

Example:

Payload (Hex) 67 01 10 67 00 FF
Data Channel Type Value
0 67 ⇒ Temperature 0110 = 272 ⇒ 27.2°C
1 67 ⇒ Temperature 00FF = 255 ⇒ 25.5°C

4.3. Full scale GPS Payload

In some scenarios, the device may send 32 bits floating point coordinates. As a drawback, altitude is given as 16 bits signed integer with 1 feet precision to fit into 11 bytes. Please notice that the coordinates format is different from the Dynamic Payload.

Since the frame can only contain GPS data, first byte must be the data channel. The device can then use either Dynamic or Packed Payload to send other data. In such case, make sure to not overlap with other data channels.

1 Byte 4 Bytes 4 Bytes 2 Bytes
Channel Latitude Longitude Altitude

4.4. History Sensor Data

When sending history data, the data channel is identified with the Frame Port. The device must send data on the Frame Port equals to the data channel added to 100.

Frame Port = Data Channel + 100

First byte of the Payload must be the Data Type, then each data is prefixed with the time elapsed between the measurement and the frame TX, expressed in seconds with a 2 bytes integer.

1 Byte 2 Bytes N Bytes 2 Bytes N Bytes ...
Data Type Delta1 Data(t-Delta1) Delta2 Data(t-Delta2) ...

4.5. Actuator Commands

After sending TX payload with either Digital and/or Analog Actuator data, Application should display UI controls accordingly to trigger the actuator with a downlink payload. As the actuator is basically a digital one (on/off, low/high), or an analog one (any value); and since the device developer is responsible of the channel mapping; data format is shared for both digital and analog actuators commands, removing the type byte.

The drawback is that digital HIGH is sent as a 1.0 analog value within a 2 bytes signed integer with 0.01 precision, eg. HIGH = 100 = 0x0064.

1 Byte 2 Bytes 1 Byte
Channel Value 0xFF

4.6. Device Configuration

This bi-directional payload allows to configure the device when used in a downlink frame, and to let the application knows of the current configuration with an uplink frame. It starts with a configuration mask on a single byte that tells what settings are included, in the following order :

ConfigMask Setting Size Definition
00000001 UTCTime 4 Unix timestamp in seconds.
00000010 TXPeriod 4 Time between each TX frames, expressed in seconds. Please remind that the TXPeriod may be limited by the Network Server.
00000100 ReadingPeriod 2 Time between each sensor reading. Useful for example to read a sensor each 60 seconds, store the value, and send data using History Payload each 5 mins using TXPeriod.
00001000 Reserved
00010000 Reserved
00100000 Reserved
01000000 Reserved
10000000 Reserved

For example, a ConfigMask equals to 0x07 defines a payload containing all settings in the same order as the setting definition table:

1 Byte 4 Bytes 4 Bytes 2 Bytes
0x07 UTCTime TXPeriod ReadingPeriod
Payload (Hex) 07 59 67 D5 47 00 00 03 84 01 2C
UTCTime 0x5967D547 = 1499977031 = 07/13/2017 8:17pm (UTC)
TXPeriod 0x00000384 = 900 seconds = 15 mins
ReadingPeriod 0x012C = 300 seconds = 5 mins

To setup the TXPeriod only, ConfigMask will be equals to 0x02, and the payload will only contains the TXPeriod value.

1 Byte 4 Bytes
0x02 TXPeriod
Payload (Hex) 02 00 00 03 84
TXPeriod 0x384 = 900 seconds = 15 mins

Omitting the ReadingPeriod will set it to TXPeriod by default, meaning sensor reading will be sent straight away.

4.7. Sensor Reading Period Configuration

We can also setup each data channel with a different reading period. In such case, the frame contains a first byte with the data channel then the period in seconds on 2 bytes.

1 Byte 2 Bytes
Channel Period

4.8. Sensor Enable Configuration

In order to enable/disable sensor or report enabled channels, a simple 8 bytes payload is used, where each bit represent a single channel.

64 bits = 8 Bytes
Enabled Channels Bit Mask
Payload (Hex) FF FF FF FF FF FF FF FF
All channels are enabled
Payload (Hex) 00 00 00 00 00 00 00 00
All channels are disabled
Payload (Hex) 00 00 00 00 00 00 00 01
Only channel 0 is enabled

Error with Cayenne LPP
#2

Nice,
Trying to get to "Data Types section but seems link is not working, so is there any library source code update somewhere so we can see what new data types are available?

Does the counter type mentionned there is now available?

Thanks


#3

I would like to request a couple of changes to the data types:

  1. Battery level- I would love to define a new type similar to humidity that can be used to represent battery level
  2. offer an option to send a digital bit-field as a set of flags. Imagine that I have 4 sensors (e.g. angle, acceleration, temp, pressure) and each one has a trigger on above and below thresholds. Unless I misunderstand the current definition, I can only send these as 24 byes - channel number, data type, value for each of 8 triggers. With a bit field approach, I could send the complete set of status in 3 bytes. For LPWAN like LoRa, saving the battery and airtime for this would be great!

Thanks


#4

Is this already implemented?
If i send data on LoRa FPORT 2, it seems it is interpreted as dynamic sensor data, and first byte is interpreted as channel, not type.