From UWB Coordinates to Useful MQTT Events: Define the Data Contract Before Integration

A useful UWB MQTT integration starts with a data contract: the meaning of each identifier, coordinate, timestamp and application event. Record which values come from the device and which your software adds. Agree how invalid, delayed or ambiguous observations will be handled before a live map or business system starts depending on them.

This guide begins after you can receive data. It provides a contract and test-fixture design, not a replacement Q1 quickstart or a tested parser for a particular firmware release.

Anchor the contract to a documented source and a real capture

The Q1 FAQ, reviewed on 6 October 2026, shows MQTT JSON with gatewayID and a tags array. Its tag examples contain id, panID, x, y and z; the stated coordinate unit is metres. The examples also distinguish tag packets from anchor packets.

Treat that published example as the starting reference. Capture a sanitized sample from the exact gateway and firmware you will use, then confirm the schema against the current manual. Preserve the original message boundary in your test fixture. Do not infer undocumented fields from a screenshot or a different product’s example.

The presence of a z field establishes that the schema represents that value. It does not establish a particular level of vertical accuracy, a validated 3D application or the behavior of another GrowSpace product.

Map the source into an application record

The application field names below are proposed names for your own software. They are not additional Q1 payload fields.

Before choosing a database key, ask which identifiers are unique within the system and which may be reused. Preserve source identifiers in their documented form. Converting an identifier to a number, stripping leading zeros or changing letter case can be destructive unless the identity rules explicitly allow it.

A map origin and orientation also need a shared definition. Metres are a unit, not a coordinate frame. Two rooms can both use metres while assigning different meanings to the same x and y values. Record the layout or frame version alongside your interpretation when the application depends on it.

Decide what time means

Receiver time answers “When did this service receive the message?” It cannot, by itself, tell you when the position was measured or how long the record spent upstream.

If the tested payload has a documented observation timestamp, define its unit, clock source and expected behavior. If it does not, preserve the limitation. Do not populate a field called measured_at with receiver time and allow a later analyst to assume it is device time.

For a zone event, your application may need several different times: the observations supporting entry, the time the rule accepted the entry and the time an external system accepted the event. Define them only where needed, and explain their provenance.

Do not assume MQTT delivery settings solve these semantic questions. Verify the actual product’s supported protocol behavior, QoS settings, retained-message behavior and reconnect behavior separately. None is prescribed or guaranteed by this article.

Make invalid and unknown data visible

A parser should have an explicit route for records it cannot use. The useful distinction is between a rejected record, an unknown asset, an incomplete observation and a valid location. Combining all four into “no movement” conceals the source of a problem.

Consider what should happen when:

• A packet type differs from the tag packet the consumer expects
• A tag has no active business-asset assignment
• A required numeric value is missing or invalid under the agreed contract
• A coordinate lies outside the configured frame or operational coverage
• An older-looking record arrives after a newer one, where a verified ordering reference exists
• Data stops arriving while the last accepted point remains on the screen

Avoid repairing data silently. If a transformation is justified, retain the transformation version and enough provenance to explain the result. Keep diagnostic samples in a restricted support location and remove credentials, personal data and confidential topology before sharing them.

Review a small fixture set before building more features

Use captured, sanitized records as the base fixtures. Add deliberately synthetic mutations only for testing and label them accordingly.

This table is a test plan. It is not evidence that tests have been run or that particular malformed packets are produced by Q1.

Keep derived events reviewable

A coordinate observation can support a proposed zone-entry event. The event additionally depends on a zone definition, identity mapping and an application rule. Store those dependencies so a support engineer can explain why an event was produced.

Similarly, receiving coordinates does not authorize a warehouse transaction. A stock movement or production-state change needs its own business rule and target-system acceptance. Keep the first integration small enough that the team can trace an observation through to its visible result.

Ready to review your contract? Compare the Q1 MQTT format documentation and the Q1 FAQ examples with a sanitized capture from your configuration. List the fields your application needs, the transformations it adds and the unresolved semantics when you discuss integration with GrowSpace.