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 !
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|
|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|
|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||✓|
|11||Device Period Configuration||✓||✓|
|13||Sensor Period Configuration||✓||✓|
|14||Sensor Enable Configuration||✓||✓|
|100-199||History Sensor Payload||✓|
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|
|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
|Payload (Hex)||01 67 FF D7|
|01 ⇒ 1||67 ⇒ Temperature||FFD7 = - 41 ⇒ - 4.1°C|
|Payload (Hex)||06 71 04 D2 FB 2E 00 00|
|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|
|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||...|
|Payload (Hex)||67 01 10 67 00 FF|
|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|
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||...|
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|
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 :
|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.|
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|
|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|
|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|
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|