Cayenne LPP 2.0

LoRa
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
5 Likes
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

1 Like
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.

5

This looks promising. Has it been merged with the specification yet? I couldn’t find anything here: Cayenne Docs nor here: cayenne-docs/LORA.md at master · myDevicesIoT/cayenne-docs · GitHub

6

the docs have not been update.

7

As this update was written a year ago I hoped it was. We’ll stick to the existing spec for now.

8

only the docs have not been updated the above specification have been implemented, so you can use them.

1 Like
9

Any chance that the specs gets updated soon?
What i still miss is a field for conveying counter values, e.g. from smart meters.

1 Like
10

the above is the only supported data types.

11

Is it possible to review the specification in its entirety by now? A complete document would have simplified the understanding and lessen risk for misunderstandings.

12

most of the info can be found here Cayenne Docs and the new add on are listed above.

13

Right, but we are looking for a new complete proposal to avoid overlaps. The changes were posted a year ago, so it’s reasonable for that to exist.

14

we did not have any major update on cayenne LPP since then.

15

We are 3 collaborating companies (Sensative AB, Sensefarm AB and Abiro AB, all in Sweden) that are very interested in a complete specification. We are all involved in sensors, actuators and IoT platforms one way or another, and a generic translator module (bidirectional) for an enhanced Cayenne LPP would be great, but we don’t want to implement something unless the specification is stable and peer-reviewed in its entirety.

1 Like
17

To clarify what we are up to (it took a while as I had to check with the others):

Sensative provides an IoT platform for initially real estate, but it’s generic, and continuously enhanced. Sensative also provides the popular Strips sensors.

Sensefarm provides sensors and applications for farming and environmental IoT.

Within IoT Abiro provides visualisation and analysis of primarily historical IoT data.

A business-driven need we see is to be able to shut off inbound data from specific sensors to make communication more efficient and battery time longer, and to provide more ways of communicating inbound and outbound. Therefore these enhancements might be what we need.

Also, showcases are often made with Pycom and Raspberry devices, so Cayenne LPP and the enhancements are valid there as well, as a lingua franca for custom devices.

If you make a complete specification in the near term we’ll provide feedback and suggestions.

We also plan to implement a generic parser/converter for the data (inbound and outbound).

Regards,
Anders Borg
Abiro AB

1 Like
18

Hello Everyone!

I wonder if there any update about LPP 2.0 implementation.

With regards

Sebastian

19

There is no new update in the implemented cayenne LPP 2.0

20

Two immediate questions please:

  1. How can user-defined types which are compatible with Cayenne be used? We have types not defined in Cayenne.
  2. (applicable to the download payload decoder in the device) For “Sensor Enable Configuration” how does the downlink payload decoder (in the device) know that the payload is encoded this way? Is it applied only on a specified port? (I might ask further, why does the binary value “enable/disable” require 8 bytes for 8 devices instead of just one byte?).
    Forgive me if I have just missed it in the documentation.
2 Likes
21

types listed above are only supported.

i did not understand what you mean by this.