MQTT data structure
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)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). The higher the index of the accelerometer measurement, the newer the measurement.
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.
This field is deprecated in software releases starting from November 2022. For customers currently using this field, the information will remain available until a release version that will be determined on a later date. For new customers, this field will be unavailable.
There are new and improved ways for obtaining zone information
1) Using the triggers feature Triggers via webhooks
2) Using the triggers feature via the triggers/trigger/+ MQTT topic (only local)
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
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.
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.