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

FPorts 1 through 63 encode sensor readings. 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

RFU means reserved for future use.

Sensor Data Types

External Sensor Data

Binary Sensor Data

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.

Sensor Errors

Note: If the device cannot read a sensor, the device reports an error. The device uses a special value or a value that is out of the normal range. 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
• pressure 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 Binary Data

FPort: 0x05 (0000 0101)

• Bit 0: Temperature reading.
• Bit 2: Binary data is in the payload.

Data: 0x00E683

• The first 2 bytes are the temperature:
  • 0x00E6 = 230 → 230 × 0.1 C = 23.0 C.
• The next byte is the binary data structure:
  • 0x83 (1000 0011).
  • Bit 7: Motion data is present.
  • Bit 6: The device does not detect motion. A 1 in this position shows motion.
  • Bit 1: Door open/close sensor data is present.
  • Bit 0: A 1 in this position shows that the door or window is open.

Example 2: 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 3: 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: Some SKUs do not have all sensors. You cannot activate a sensor that the SKU does not have. If a Set request sets the enable bit for that sensor, the Report response does not fail. The device sets the enable bit to 0.

External Sensor IDs

Note: You must install the external sensor before you can activate it. The external sensor works with all MQflex FV3 SKUs that have firmware v0.57.0 or later. You cannot activate Water Leak detection and the External Sensor at the same time.

Data Caching Bit Map

1 = Active. 0 = Not active.

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.

Example 3: Activate the Door/Window Sensor

Packet: 050402

Parameter and value pair 0: 050402

• Parameter: 0x05 → Enable/Disable Sensor.
• Value: 0x0402 → Bit mask → Activate the Door/Window 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, probe calibration, 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.