Developer Guide

Message Formats & Conversion

1. Overview

In IoTRoutes, every IoT communication — whether device → platform or platform → device — follows a structured transformation pipeline.
The goal is to normalize all message formats into a standard internal representation called the Platform Message Structure (PMS).

This approach allows the platform to:

• Process heterogeneous device protocols (MQTT, HTTP, CoAP, etc.)

• Apply uniform workflows and attribute interpretation

• Simplify command generation and data storage

Messages received or sent always pass through Workflows that interpret, convert, enrich, and validate data before persistence or transmission.

2. Message Direction

There are two primary message directions handled by the system:

Each message direction uses a different workflow chain:

• Inbound Workflow: Converts external message to PMS, interprets and stores attributes.

• Outbound Workflow: Converts PMS to the device’s expected format (JSON, binary, or custom).

3. Platform Message Structure (PMS)

The PMS is a normalized, device-independent JSON schema used internally by IoTRoutes.
It represents messages in a unified way, regardless of the original device protocol or payload format.

Example PMS (Inbound message)

Example PMS (Outbound command)

The PMS serves as the core data model throughout all processing phases.

4. Message Lifecycle

Each message follows a lifecycle that tracks its state from creation to completion.

The lifecycle helps monitor reliability and processing performance via KPIs and dashboards.

5. Inbound Message Conversion

Step 1 – Reception

Messages arrive from one of the supported brokers (MQTT, HTTP, AMQP, etc.).
Each incoming payload is associated with metadata such as topic, source, and timestamp.

Step 2 – Workflow Parsing

The Inbound Workflow is triggered automatically.
Typical actions include:

• Parse JSON or binary data from the device payload.

• Extract attributes and convert them to standard types.

• Assign device identity using mapping rules.

• Normalize to PMS format.

Step 3 – Interpretation

Once converted, the PMS is processed by the Attribute Interpreters — logic modules that classify values (Normal, Faulty, Warning, etc.) or apply calculations.

Step 4 – Storage

After successful interpretation, the PMS data is inserted into the Attributes Ledger, where it becomes available for dashboards, KPIs, and analytics.

6. Outbound Message Conversion

When sending commands or configuration updates, workflows generate PMS structures that represent intended device actions.

The Outbound Workflow then:

• Reads the PMS command.

• Applies format conversion rules (e.g., JSON, XML, binary).

• Injects protocol-specific fields (topic, QoS, headers).

• Publishes the final message via the broker.

This allows the same logical command to target multiple device types with minimal reconfiguration.

Example Conversion

7. Workflow Actions for Conversion

Developers can implement conversion logic using workflow actions:

These actions can be chained for full control over how messages are received and emitted.

8. Using Expressions in Conversion

Formula expressions can dynamically adapt message content during conversion.

Example:

This allows the developer to build context-aware transformations directly inside workflows — no coding required.

9. Message Validation and Error Handling

If a message fails validation (e.g., missing device ID or invalid format):

• It is flagged as BadMessage.

• Logged in the workflow execution history.

• Optionally, moved to an Error Queue for reprocessing or review.

Administrators can monitor these cases via dashboards or KPI panels (e.g., “Bad messages in last 24h”).

10. Advanced Customization

Developers can create custom conversion rules using:

• Custom Workflow Actions (extend base converters).

• External API calls to fetch mapping definitions.

• Conditional routing: forward message to other brokers or systems.

• Transformation templates for complex payloads (e.g., XML→JSON mapping).

This makes IoTRoutes suitable for both edge-level integration and enterprise back-end synchronization.

11. Best Practices

• Always normalize inbound data as early as possible.

• Use PMS consistently — never store raw payloads unless required.

• Implement validation in the first workflow step to prevent propagation of bad data.

• Keep outbound conversion rules modular and reusable.

• Use Message Simulation for testing conversions before deploying to production.

12. Example: Complete Conversion Workflow

Goal: Convert device raw payload to PMS, store in ledger, and trigger alert if threshold exceeded.

1. ParseMessage → extract JSON fields.

2. BuildPMS → map temp → Temperature.

3. InterpretAttributes → classify “Faulty” if Temperature > 60.

4. InsertLedger → save interpreted attributes.

5. GenerateCommand → send cooling command to device if needed.