MQPS and Other Data Reporting

The device uses the MachineQ Payload Standard (MQPS) to encode sensor readings and configuration messages. MQPS is a very efficient packet format. This page gives the MQPS specification for the onboard temperature sensor and the onboard humidity sensor. The device also supports other commands, for example the last reset reason and the version request.

Packet Overview

MQPS is specific to LoRaWAN. MQPS uses the LoRaWAN packet FPort and the packet direction to encode more data.

• FPorts 1 through 223 encode the contents and the format of the payload (data section) of each packet.
• The direction (uplink or downlink) encodes more data.

The flow chart that follows shows how the FPort and the direction identify the packet types on this page.

Sensor Reading

The device sends sensor readings on FPorts 1 through 3. The device uses the FPort number as a bit mask. Each bit identifies one sensor. The decoder uses the bit mask to find the reading type and to parse the payload. The payload has no other format data or size data.

FPort Format

The device has only the temperature sensor and the humidity sensor. The device does not set bits 2 through 7.

Sensor Data Types

Payload Order

The payload contains the readings for all sensors that have a bit set to 1 in the FPort bit mask. The readings are in bit order, from the least significant bit. If both bits are set, the temperature reading is first and the humidity reading follows.

Sensor Errors

Note: If the device cannot read a sensor, the device reports an error. The device uses a special value. When an error occurs, the decoded_payload does not contain the field for that sensor. The decoder adds an error field. The decoder decodes all valid values in the same payload correctly.

The possible error messages are:

• temperature reading
• humidity reading

This example shows a decoded payload with valid humidity data and a temperature error:

"decoded_payload": {
  "humidity": "55.0",
  "error": ["temperature reading"]
}

Example 1: Temperature and Humidity

FPort: 0x03 (0000 0011)

• Bit 0: Temperature reading.
• Bit 1: Humidity reading.

Data: 0x00E611

• The first 2 bytes are the temperature:
  • 0x00E6 = 230 → 230 × 0.1 C = 23.0 C.
• The next byte is the humidity:
  • 0x11 = 17 → 17 × 0.5% RH = 8.5% RH.

Example 2: Temperature and Humidity Errors

FPort: 0x03 (0000 0011)

• Bit 0: Temperature reading.
• Bit 1: Humidity reading.

Data: 0x8000FF

• The first 2 bytes are the temperature:
  • 0x8000 → Temperature error.
• The next byte is the humidity:
  • 0xFF → Humidity error.

Configuration

Configuration packets control the operation of the device. Use a LoRaWAN downlink to set the configuration or to get the configuration from the device.

Configuration Message Format (Set and Report)

Configuration Message Format (Get)

Configuration Parameters

Note: Integers are unsigned. If a parameter has a different data type, the table gives the data type.

Note: The device does not support parameters 0x07 (Movement Threshold), 0x08 (Water Leak Monitoring Config), 0x09 (Pressure Report Delta), 0x0C (External Sensor), and 0x0E (RTD Delta). These parameters are for sensors that the device does not have.

Data Caching Bit Map

1 = Active. 0 = Not active.

RFU means reserved for future use.

Set and Report

Set packets and Report packets use the same format and the same FPort number. The packet format is a list of parameter and value pairs. When the device receives a valid Set request, the device sends a Report packet. The Report packet is an exact copy of the Set request. If a parameter or a value is not valid, the device sends 0xFF.

Example 1: Reporting Period and Sample Period

Packet: 01070802003c

Parameter and value pair 0: 010708

• Parameter: 0x01 = 1 → Reporting Period.
• Value: 0x0708 = 1800 → 1800 × 2 sec = 3600 sec = 1 hour.

Parameter and value pair 1: 02003c

• Parameter: 0x02 = 2 → Sensor Sample Period.
• Value: 0x003c = 60 → 60 × 2 sec = 120 sec = 2 minutes.

Example 2: Configure the Temperature and Humidity Sensors

Packet: 030a0402050300

Parameter and value pair 0: 030a

• Parameter: 0x03 = 3 → Temperature Report Delta.
• Value: 0x0a = 10 → 10 × 0.1 C = 1 C delta.

Parameter and value pair 1: 0402

• Parameter: 0x04 = 4 → Humidity Report Delta.
• Value: 0x02 = 2 → 2 × 0.5% RH = 1% RH delta.

Parameter and value pair 2: 050300

• Parameter: 0x05 → Enable/Disable Sensor.
• Value: 0x0300 → Bit mask → Activate the Temperature sensor and the Humidity sensor.

Get

Use FPort 222 to send a Get configuration downlink to the device. The packet format is a list of parameters. The device sends the requested configuration values on FPort 221.

Example: Get the Reporting Period and the Sensor Sample Period

Get request downlink on FPort 222: 0102

• Parameter: 0x01 = 1 → Reporting Period.
• Parameter: 0x02 = 2 → Sensor Sample Period.

Response uplink on FPort 221: 01070802003c

Parameter and value pair 0: 010708

• Parameter: 0x01 = 1 → Reporting Period.
• Value: 0x0708 = 1800 → 1800 × 2 sec = 3600 sec = 1 hour.

Parameter and value pair 1: 02003c

• Parameter: 0x02 = 2 → Sensor Sample Period.
• Value: 0x003c = 60 → 60 × 2 sec = 120 sec = 2 minutes.

Common Configurations

The tables that follow give the recommended configuration settings for common use cases of the device. The first table shows the related parameters. The values in bold are the parameters that change most often for different customer needs.

The table that follows gives the full configuration downlink for each common use case.

Reset Reason

At startup, the device sends the last reset reason on FPort 220. The device uses this format:

Hardware Reset Reason

Each bit in the Hardware Reset Reason byte identifies one cause of the last reset. If a bit is set to 1, the related cause started the last reset.

Software Reset Reason

The Software Reset Reason codes have these meanings:

Note: The device sends this uplink as a confirmed uplink.

Join Reason

After each successful join request and join response procedure, the device sends the reason for the join and related data. For the first join procedure after a power cycle, the device sends only the Reset Reason uplink.

The device sends the last join reason on FPort 217. The device uses this format:

Join Count

The Join Count field gives the number of Join Requests that the device sent before it received the Join Accept message. If the device sent more than 255 Join Requests, the Join Count is 255.

Other Info

The Other Info field gives more data about the join request.

Join Reason Codes

The Join Reason codes have these meanings:

Note: The device sends this uplink as a confirmed uplink.

What's Next?

• Sensor Operation - Supported sensors, sensor reporting, sensor operation, data caching, and battery depassivation.
• LoRaWAN Commands and Responses - Device status and device version requests and responses.
• DFU Instructions - Update the device firmware with nRF Connect for Mobile.