· Eduardo Vieira · IIoT · 2 min read
Designing MQTT Payload Formats for IIoT
How to structure MQTT payloads that serve operators, analytics teams, and enterprise systems without creating technical debt.
Designing MQTT Payload Formats for IIoT
MQTT makes it easy to move data, but the payload format determines whether downstream systems can use it effectively. Here’s how I design payloads that scale across operations, IT, and analytics teams.
1. Choose the Right Encoding
| Encoding | Pros | Cons | Use When |
|---|---|---|---|
| JSON | Human-readable, ubiquitous tooling | Larger payloads, slower parsing | General telemetry, dashboards |
| Binary (protobuf, MessagePack) | Compact, fast | Requires schema management | Bandwidth-constrained links |
| CSV | Simple, low overhead | Ambiguous types, limited metadata | Legacy integrations |
| Sparkplug B | Standardized, stateful | Requires specific clients | Enterprise MQTT brokers |
Most of my projects start with JSON for readability, then evolve to Sparkplug B when scaling.
2. Define a Data Contract
- Use consistent field names (snake_case or camelCase) and document them.
- Include timestamps (
ISO 8601), units, and quality flags. - Version payloads (
schema_version) to manage changes.
Example JSON:
{
"schema_version": "1.2",
"asset": "line01.packager",
"timestamp": "2025-04-09T14:30:05Z",
"process": {
"oee": 0.87,
"temperature_c": 192.5,
"pressure_bar": 4.2
},
"alarms": [
{"code": 102, "severity": "high", "message": "Door open"}
]
}3. Support Localization and Units
- Standardize units (SI preferred) and convert at the edge if needed.
- Include language-specific message catalogs if your operators work in multiple languages.
4. Handle Batches and Streaming
- For fast-changing signals, send incremental updates with only changed fields.
- For historical uploads, package arrays of measurements with start/end timestamps.
5. Include Quality and Source Metadata
- Add
qualityfields (good, bad, uncertain) and sampling intervals. - Identify the data source (
plc_id,gateway_id, firmware version) for traceability.
6. Security Considerations
- Sign payloads or use TLS with mutual authentication.
- Avoid embedding secrets or credentials inside payloads.
- Encrypt sensitive fields at the application level if regulatory requirements apply.
7. Testing and Validation
- Create JSON Schemas or protobuf definitions and validate messages in CI pipelines.
- Use digital twins or simulators to replay payloads before production rollouts.
8. Documentation and Governance
- Maintain payload definitions in a shared repository with changelog.
- Communicate deprecations ahead of time and support dual schemas during transitions.
Well-structured payloads make MQTT a powerful backbone for smart manufacturing. Treat your payload format like an API contract, and downstream teams will build on it confidently.