Each MQTT packet consists of an array with tag position updates:

  • When you are using the local MQTT stream there will be no batching and each tag position update will be sent in a separate MQTT packet.

  • When you are using the cloud MQTT stream there is possibly batching of tag position updates and each MQTT packet could contain several tag position updates. See the section MQTT data rate under Connect through the cloud on the MQTT API page for more info.

The MQTT data structure will differ a bit from tag to tag, as not all tags have the same sensors and interfaces. Examples of the structure for each tag can be found below.

Field definitions

tagId : string

The ID of the tag for which the MQTT packet contains information. The tag ID can be set through the Pozyx Device Configurator (https://docs.pozyx.io/enterprise/Configuring-the-tags.1224015986.html#Configuringthetags-General), and can also be found in the web application.

timestamp : number

The timestamp of when the position was calculated in Epoch time. You can convert it to a more human readable time with the following snippet:

import datetime

ts = datetime.datetime.fromtimestamp(1616424015.121358).strftime('%Y-%m-%d %H:%M:%S')
print(ts)
PY

data.metrics.latency : number

The duration between the first receipt of a packet of the anchors and the time that the position is pushed on the MQTT stream (= the processing time on the gateway), expressed in ms.

data.metrics.rates.success : number

The update rate of the tag when only the successful position calculations are being taken into account, expressed in Hz.

E.g. If the update rate of the tag is 10 Hz, but the position calculation fails for 50% of the tag blinks, the success rate would be 5 Hz.

This is calculated over a number of blinks equal to the update rate with a minimum of 10: If the update rate of your tag is < 10 Hz, the system will calculate the rate over 10 blinks. If the update rate is > 10 Hz (e.g. 15 Hz), the system will calculate the rate over the update rate (e.g. 15 blinks).

data.metrics.rates.update : number

The update rate of the tag, expressed in Hz.

data.metrics.rates.packetLoss : number

The packet loss of the tag (= tag blinks that do not make it to the gateway, either because they do not arrive at an anchor or because there’s loss on the network), expressed in Hz.

data.tagData.blinkIndex : number

Index identifying the signal that the tag sent out. The combination of tagId + blinkIndex will uniquely identify a UWB packet, and will be used by the gateway to combine the packets received by the different anchors to calculate the position.

data.tagData.accelerometer : array

An array of acceleration measurements. The acceleration is measured along 3-axis (so each accelerometer update is an array of 3 values) and is expressed in mg (milli-G's). More information about the accelerometer can be found here: https://docs.pozyx.io/enterprise/Configuring-the-tags.1224015986.html#Configuringthetags-Accelerometersettings

data.anchorData : array

An array of the anchors that were being used to calculate the position, and the RSS of the UWB packet at each anchor’s antenna.

data.coordinates.x : number

The x-coordinate of the tag, expressed in mm.

data.coordinates.y : number

The y-coordinate of the tag, expressed in mm.

data.coordinates.z : number

The z-coordinate of the tag, expressed in mm.

data.zones : array

An array of the zones in which the tag is present. Each array element is an object with inside it the zone ID and the zone name.

success : boolean

Boolean which will indicate whether a position could be calculated or not.

errorCode : string

Text message which will give you the reason why the position could not be calculated in case success is false.

Examples

Industrial tag

Success: true
[
  {
    "version": "2.0",
    "tagId": "200000001",
    "timestamp": 1616424015.121358,
    "data": {
      "metrics": {
        "latency": 16,
        "rates": {
          "success": 1.95,
          "update": 1.94,
          "packetLoss": 0.03
        }
      },
      "tagData": {
        "blinkIndex": 131004,
        "accelerometer": [
          [
            132,
            273,
            -1042
          ],
          [
            109,
            542,
            -851
          ],
          [
            164,
            27,
            -644
          ],
          [
            296,
            -109,
            -687
          ],
          [
            312,
            -238,
            -968
          ],
          [
            -636,
            429,
            -2000
          ],
          [
            35,
            66,
            -984
          ]
        ]
      },
      "anchorData": [
        {
          "tagId": "200000001",
          "anchorId": "62307",
          "rss": -85.12
        },
        {
          "tagId": "200000001",
          "anchorId": "51607",
          "rss": -82.11
        },
        {
          "tagId": "200000001",
          "anchorId": "10204",
          "rss": -82.21
        },
        {
          "tagId": "200000001",
          "anchorId": "17417",
          "rss": -79.97
        },
        {
          "tagId": "200000001",
          "anchorId": "28205",
          "rss": -79.28
        },
        {
          "tagId": "200000001",
          "anchorId": "46990",
          "rss": -78.23
        },
        {
          "tagId": "200000001",
          "anchorId": "3265",
          "rss": -79.18
        },
        {
          "tagId": "200000001",
          "anchorId": "22367",
          "rss": -83.34
        },
        {
          "tagId": "200000001",
          "anchorId": "50602",
          "rss": -79.31
        }
      ],
      "coordinates": {
        "x": 1551,
        "y": 25079,
        "z": 1000
      },
      "score": 0,
      "type": 1,
      "zones": [
        {
          "name": "Zone 3",
          "id": "60549fc07f2c21a22d79462a"
        }
      ]
    },
    "tagType": "2.0",
    "success": true
  }
]
JSON
Success: false
[
  {
    "version": "2.0",
    "tagId": "200000001",
    "timestamp": 1616424098.3551848,
    "data": {
      "metrics": {
        "latency": 205,
        "rates": {
          "success": 1.69,
          "update": 1.86,
          "packetLoss": 0.03
        }
      },
      "tagData": {
        "blinkIndex": 131170,
        "accelerometer": [
          [
            35,
            -945,
            -191
          ],
          [
            3,
            -953,
            -148
          ],
          [
            -31,
            -957,
            -136
          ],
          [
            -15,
            -953,
            -140
          ],
          [
            0,
            -968,
            -125
          ],
          [
            -7,
            -957,
            -136
          ],
          [
            15,
            -949,
            -144
          ]
        ]
      },
      "anchorData": [
        {
          "tagId": "200000001",
          "anchorId": "46990",
          "rss": -93.22
        },
        {
          "tagId": "200000001",
          "anchorId": "3265",
          "rss": -97.75
        }
      ]
    },
    "tagType": "2.0",
    "success": false,
    "errorCode": "7 - Positioning result is considered invalid"
  }
]
JSON

Wearable tag (interactive)

The status and events fields under tagData are related to the button configuration. More information about this can be found here: https://docs.pozyx.io/enterprise/Configuring-the-tags.1224015986.html#Configuringthetags-Buttonconfiguration. When you select the Off (LEDs on) or the Off (LEDs off) button behavior, these fields will not be present.

Success: true
[
  {
	"version": "2.0",
    "tagId": "7057",
    "timestamp": 1615930183.68305,
    "data": {
      "metrics": {
        "latency": 24,
        "rates": {
          "success": 1.75,
          "update": 1.75,
          "packetLoss": 0.04
        }
      },
      "tagData": {
        "blinkIndex": 51718,
        "status": "2",
        "events": [
          {
            "type": 1,
            "timestamp": 1615930179.1052644
          },
          {
            "type": 0,
            "timestamp": 1615930179.827918
          },
          {
            "type": 0,
            "timestamp": 1615930180.628115
          }
        ],
        "accelerometer": [
          [
            515,
            -42,
            -882
          ],
          [
            347,
            -27,
            -792
          ],
          [
            27,
            0,
            -710
          ],
          [
            82,
            -7,
            -589
          ],
          [
            -113,
            31,
            -953
          ],
          [
            -15,
            -19,
            -1007
          ]
        ]
      },
      "anchorData": [
        {
          "tagId": "7057",
          "anchorId": "22367",
          "rss": -120
        },
        {
          "tagId": "7057",
          "anchorId": "28205",
          "rss": -82.36
        },
        {
          "tagId": "7057",
          "anchorId": "3265",
          "rss": -85.53
        },
        {
          "tagId": "7057",
          "anchorId": "46990",
          "rss": -80.82
        },
        {
          "tagId": "7057",
          "anchorId": "17417",
          "rss": -88.05
        },
        {
          "tagId": "7057",
          "anchorId": "50602",
          "rss": -88.05
        }
      ],
      "coordinates": {
        "x": 1148,
        "y": 25191,
        "z": 350
      },
      "score": 0.25350121652747626,
      "type": 1,
      "zones": [
        {
          "name": "Office Space",
          "id": "602bf2634f2e54c6d901b392"
        },
        {
          "name": "Desk 1",
          "id": "604a716e52694c06b1c27879"
        }
      ]
    },
    "success": true
  }
]
JSON
Success: false
[
  {
    "version": "2.0",
    "tagId": "7057",
    "timestamp": 1615984440.6194596,
    "data": {
      "metrics": {
        "latency": 30,
        "rates": {
          "success": 0,
          "update": 2.01,
          "packetLoss": 0
        }
      },
      "tagData": {
        "blinkIndex": 52586,
        "status": "1",
        "events": [
          {
            "type": 0,
            "timestamp": 1615984434.397999
          }
        ],
        "accelerometer": [
          [
            -23,
            -15,
            980
          ],
          [
            -23,
            -11,
            984
          ],
          [
            -23,
            -11,
            988
          ],
          [
            -27,
            -11,
            984
          ],
          [
            -23,
            -7,
            984
          ],
          [
            -23,
            -3,
            988
          ],
          [
            -19,
            -7,
            984
          ]
        ]
      },
      "anchorData": [
        {
          "tagId": "7057",
          "anchorId": "46990",
          "rss": -81.64
        },
        {
          "tagId": "7057",
          "anchorId": "51607",
          "rss": -92.26
        },
        {
          "tagId": "7057",
          "anchorId": "28205",
          "rss": -81.65
        },
        {
          "tagId": "7057",
          "anchorId": "17417",
          "rss": -82.8
        },
        {
          "tagId": "7057",
          "anchorId": "3265",
          "rss": -83.15
        },
        {
          "tagId": "7057",
          "anchorId": "62307",
          "rss": -120
        },
        {
          "tagId": "7057",
          "anchorId": "10204",
          "rss": -95.34
        },
        {
          "tagId": "7057",
          "anchorId": "22367",
          "rss": -97.27
        },
        {
          "tagId": "7057",
          "anchorId": "50602",
          "rss": -82.66
        }
      ]
    },
    "success": false,
    "errorCode": "7 - Positioning result is considered invalid"
  }
]
JSON

Wearable tag (tracking)

The status and events fields under tagData are related to the button configuration, and even though the Tracking edition of the Wearable tag does not have a button it is running the same firmware as the Interactive edition and will therefor show these fields. More information about this can be found here: https://docs.pozyx.io/enterprise/Configuring-the-tags.1224015986.html#Configuringthetags-Buttonconfiguration. When you select the Off (LEDs on) or the Off (LEDs off) button behavior, these fields will not be present.

Success: true
[
  {
    "version": "2.0",
    "tagId": "6987",
    "timestamp": 1615986231.903762,
    "data": {
      "metrics": {
        "latency": 14,
        "rates": {
          "success": 1,
          "update": 1.01,
          "packetLoss": 0
        }
      },
      "tagData": {
        "blinkIndex": 333,
        "status": "0",
        "events": [],
        "accelerometer": [
          [
            50,
            35,
            964
          ],
          [
            54,
            35,
            968
          ],
          [
            46,
            31,
            957
          ],
          [
            46,
            35,
            972
          ],
          [
            50,
            35,
            964
          ],
          [
            50,
            35,
            964
          ],
          [
            23,
            11,
            984
          ],
          [
            15,
            23,
            992
          ],
          [
            58,
            31,
            960
          ],
          [
            54,
            31,
            953
          ],
          [
            58,
            -42,
            1042
          ],
          [
            70,
            27,
            976
          ],
          [
            70,
            42,
            960
          ]
        ]
      },
      "anchorData": [
        {
          "tagId": "6987",
          "anchorId": "28205",
          "rss": -83.25
        },
        {
          "tagId": "6987",
          "anchorId": "46990",
          "rss": -83.78
        },
        {
          "tagId": "6987",
          "anchorId": "3265",
          "rss": -90.44
        },
        {
          "tagId": "6987",
          "anchorId": "17417",
          "rss": -87.6
        },
        {
          "tagId": "6987",
          "anchorId": "50602",
          "rss": -86.6
        }
      ],
      "coordinates": {
        "x": 2255,
        "y": 24210,
        "z": 350
      },
      "score": 0.8052230929885561,
      "type": 1,
      "zones": [
        {
          "name": "Office Space",
          "id": "602bf2634f2e54c6d901b392"
        },
        {
          "name": "Desk 1",
          "id": "604a716e52694c06b1c27879"
        }
      ]
    },
    "success": true
  }
]
JSON
Success: false
[
  {
    "version": "2.0",
    "tagId": "6987",
    "timestamp": 1615986238.844214,
    "data": {
      "metrics": {
        "latency": 220,
        "rates": {
          "success": 0.9,
          "update": 0.99,
          "packetLoss": 0
        }
      },
      "tagData": {
        "blinkIndex": 340,
        "status": "0",
        "events": [],
        "accelerometer": [
          [
            929,
            -82,
            -390
          ],
          [
            1023,
            -50,
            -210
          ],
          [
            1042,
            -3,
            -128
          ],
          [
            1039,
            0,
            -58
          ],
          [
            1035,
            3,
            -31
          ],
          [
            1023,
            7,
            -31
          ],
          [
            1023,
            15,
            0
          ],
          [
            1007,
            23,
            -3
          ],
          [
            1050,
            31,
            42
          ],
          [
            1042,
            35,
            50
          ],
          [
            1058,
            35,
            50
          ],
          [
            1031,
            27,
            46
          ]
        ]
      },
      "anchorData": [
        {
          "tagId": "6987",
          "anchorId": "46990",
          "rss": -87.57
        },
        {
          "tagId": "6987",
          "anchorId": "28205",
          "rss": -105.05
        }
      ]
    },
    "success": false,
    "errorCode": "7 - Positioning result is considered invalid"
  }
]
JSON

Developer tag

Success: true
[
  {
    "version": "2.0",
    "tagId": "30331",
    "timestamp": 1615984968.8071718,
    "data": {
      "metrics": {
        "latency": 28,
        "rates": {
          "success": 0.76,
          "update": 1.04,
          "packetLoss": 0
        }
      },
      "tagData": {
        "blinkIndex": 127,
        "acceleration": {
          "x": -12,
          "y": 69,
          "z": 949
        },
        "gyro": {
          "x": -0.0625,
          "y": -0.0625,
          "z": -0.0625
        },
        "magnetic": {
          "x": -8.75,
          "y": 39.375,
          "z": -27.25
        },
        "eulerAngles": {
          "x": 29.6875,
          "y": -0.625,
          "z": -4.4375
        },
        "quaternion": {
          "x": 0.9658203125,
          "y": 0.0389404296875,
          "z": -0.00457763671875,
          "w": -0.25634765625
        },
        "gravityVector": {
          "x": -10,
          "y": 76,
          "z": 977
        },
        "pressure": 98543.25,
        "customSensors": [
          {
            "name": "customPayload",
            "value": ""
          }
        ]
      },
      "anchorData": [
        {
          "tagId": "30331",
          "anchorId": "28205",
          "rss": -82.12
        },
        {
          "tagId": "30331",
          "anchorId": "46990",
          "rss": -80.92
        },
        {
          "tagId": "30331",
          "anchorId": "51607",
          "rss": -104.19
        },
        {
          "tagId": "30331",
          "anchorId": "3265",
          "rss": -85.57
        },
        {
          "tagId": "30331",
          "anchorId": "17417",
          "rss": -89.79
        },
        {
          "tagId": "30331",
          "anchorId": "10204",
          "rss": -120
        },
        {
          "tagId": "30331",
          "anchorId": "22367",
          "rss": -105.53
        },
        {
          "tagId": "30331",
          "anchorId": "50602",
          "rss": -87.81
        }
      ],
      "coordinates": {
        "x": 581,
        "y": 26713,
        "z": 350
      },
      "score": 0,
      "type": 1,
      "zones": [
        {
          "name": "Office Space",
          "id": "602bf2634f2e54c6d901b392"
        }
      ]
    },
    "success": true
  }
]
JSON
Success: false
[
  {
    "version": "2.0",
    "tagId": "30331",
    "timestamp": 1615984966.8530037,
    "data": {
      "metrics": {
        "latency": 11,
        "rates": {
          "success": 0.81,
          "update": 1.05,
          "packetLoss": 0
        }
      },
      "tagData": {
        "blinkIndex": 125,
        "acceleration": {
          "x": -12,
          "y": 69,
          "z": 950
        },
        "gyro": {
          "x": -0.0625,
          "y": 0.0625,
          "z": 0.0625
        },
        "magnetic": {
          "x": -8.75,
          "y": 38.75,
          "z": -28.0625
        },
        "eulerAngles": {
          "x": 29.6875,
          "y": -0.625,
          "z": -4.4375
        },
        "quaternion": {
          "x": 0.9658203125,
          "y": 0.0389404296875,
          "z": -0.00457763671875,
          "w": -0.25634765625
        },
        "gravityVector": {
          "x": -10,
          "y": 76,
          "z": 977
        },
        "pressure": 98535.25,
        "customSensors": [
          {
            "name": "customPayload",
            "value": ""
          }
        ]
      },
      "anchorData": [
        {
          "tagId": "30331",
          "anchorId": "28205",
          "rss": -82.36
        },
        {
          "tagId": "30331",
          "anchorId": "46990",
          "rss": -80.28
        },
        {
          "tagId": "30331",
          "anchorId": "51607",
          "rss": -104.88
        },
        {
          "tagId": "30331",
          "anchorId": "3265",
          "rss": -86.24
        },
        {
          "tagId": "30331",
          "anchorId": "17417",
          "rss": -91.63
        },
        {
          "tagId": "30331",
          "anchorId": "10204",
          "rss": -120
        },
        {
          "tagId": "30331",
          "anchorId": "22367",
          "rss": -120
        },
        {
          "tagId": "30331",
          "anchorId": "50602",
          "rss": -87.65
        }
      ]
    },
    "success": false,
    "errorCode": "7 - Positioning result is considered invalid"
  }
]
JSON