Developer Guide

Attribute Interpreters

1. Overview

Attribute Interpreters are the functional bridge between raw IoT data and understandable business information.
When an inbound workflow receives a message, its attribute values are normalized into the Platform Message Structure (PMS).
Before they are written into the Ledger, IoTRoutes applies one or more interpreters that analyze or transform these raw values into a consistent, typed, and possibly categorized result.

Interpreters can:

• Convert or normalize sensor readings (e.g., raw ADC → ° C temperature).

• Map numeric or boolean values into qualitative levels (e.g., 0 → Off / 1 → On).

• Detect conditions and classify them (e.g., fault levels, good/bad status).

• Execute custom formula expressions or API calls for advanced logic.

2. Interpreter Structure

Each interpreter definition includes the following properties:

Interpreters can be attached globally to attribute definitions or selectively assigned to a device class.

3. Interpreter Execution in Workflows

When an inbound workflow processes a message:

1. The raw PMS payload arrives with all attribute key–value pairs.

2. For each attribute, the workflow checks if an interpreter is defined.

3. If yes, the interpreter logic is executed:

   • Simple mappings are applied directly.

   • If an Expression exists, it is evaluated.

   • If Call API is configured, the platform performs the request and uses the response value.

4. The interpreted result is written into the Ledger and stored for analytics, dashboards, or KPIs.

4. Levels and Range Mappings

IoTRoutes supports interpreting attributes through range mapping or discrete levels.

Example 1 – Range Mapping

The interpreter converts the numeric measurement into a qualitative state.
This level is later used by dashboards, alerts, and filters (for example, “Devices with High Temperature”).

5. Formula-Based Interpreters

Interpreters can include a Formula Expression to compute the final value dynamically.

Example 2 – Formula Expression:

Example 3 – Derived Computation:

➡ Computes power (kW) from voltage and current readings.

Formula syntax and functions are identical to those used in workflows (see Section 5 – Formula Expressions).

6. API-Based Interpreters

For cases where value conversion depends on external data (for example, calibration tables or dynamic thresholds), an interpreter can call an API endpoint.

Parameters:

• HTTP Method (GET/POST)

• URL template (e.g. https://api.external.com/convert?raw=@{value})

• Result mapping (field in the JSON response to read)

Typical Use Cases:

• Use calibration data stored in a remote system.

• Enrich a GPS coordinate with address information.

• Fetch tolerance limits based on device model.

7. Advanced Usage – Chained Interpreters

Multiple interpreters can be chained when an attribute requires multi-step conversion.
Example:

1. Raw voltage → Normalized voltage (V)

2. Normalized voltage → Health Level (Good/Warning/Faulty)

Chaining is configured in the interpreter sequence field.
Each interpreter output becomes the next input, allowing complex transformations while keeping logic modular.

8. Testing and Debugging Interpreters

• Use the Test Interpreter option to run a sample value and verify the output.

• Execution results are logged in Workflow Log with both raw and interpreted values.

• Developers can enable Verbose Mode to inspect intermediate results (API responses, formula evaluations).

• Invalid or failing interpreters do not block message ingestion; they mark the attribute with a “Conversion Error” status visible in logs.

9. Best Practices

• Prefer formula interpreters for lightweight logic instead of adding workflow steps.

• Use clear and consistent naming conventions (Temperature.Level, Voltage.Normalized).

• Avoid making blocking API calls in high-frequency interpreters—cache responses when possible.

• Always define default or fallback values for range and formula results.

• Test interpreters with real device data before enabling them globally.