Data Flow & Automation Architecture Guide

This guide explains how data moves through Virtuino Cloud — from the moment a value is sent, all the way to storage, live dashboards, MQTT subscribers, rules, scripts and HTTP requests. Knowing this path helps you design reliable automations and quickly find out why something did not happen.

1. How Data Enters the Platform

Every value is written to a field. The field's name is also its MQTT topic — for example kitchen/temperature. Whoever sends the value, it carries a source tag that travels with it through the whole platform and decides what it is allowed to trigger.

2. The Central Hub: How Every Value is Processed

No matter where a value comes from, it passes through the same processing function, in this order:

1. Size check. A historical field accepts values up to 512 characters, a standard field up to 1 MB. A larger value is rejected completely — nothing below runs — and the rejection is shown in the Debug Monitor.
2. Confirmation check. If the value is a command to a field that waits for confirmation, it is only sent to the device; the remaining steps run when the device echoes it back. See Section 8.
3. Forward to MQTT subscribers (MQTT values only). A value published by one client is passed on to every client subscribed to that topic — other boards, the Virtuino IoT app, Node-RED. Echoes of a command the device just received are not forwarded again (Section 10).
4. Save to the database. A historical field keeps every value; a standard field keeps only the latest one. If the sender supplied its own timestamp (time), that time is stored.
5. Publish via MQTT — only when the writer asked for it: the "Publish via MQTT" option of a widget, rule, scheduler or script output, or "publish": true in an HTTP API request.
6. Update live dashboards — every open dashboard showing the field updates instantly.
7. Run the triggers, in parallel: the JSON Splitter, scripts, rules and HTTP Requests that watch this field. Which of them may run depends on the source tag — see Section 10.

3. MQTT: Two Channels That Never Cross

In your device code, a field is one topic: publish to kitchen/temperature to send a value, subscribe to kitchen/relay to receive commands. There is nothing to register besides the field itself — the topic is the field name, slashes included. For connection details and examples see the MQTT guide.

Under the hood the broker keeps two separate channels for every field, and picks the right one automatically: what a client publishes goes to the platform's inbound channel, and what a client subscribes to is read from the outbound channel. Nothing about this needs configuring.

Fields that wait for confirmation also get a third, read-only topic, {field}/state — for example kitchen/relay/state. It carries the value only once the device has confirmed it, so apps that subscribe to it always show the real state. See Section 8.

4. Live Dashboards

Every value the hub saves is also pushed to all open dashboards that show that field, through a live WebSocket connection — no page refresh needed:

• A value sent by an MQTT or HTTP device appears on the dashboard in under a second.
• A value written by a rule, script, scheduler or the JSON Splitter appears immediately too.
• Everyone who has the dashboard open sees the same update at the same time.

One exception: for a field that waits for confirmation, a new command is saved and pushed to dashboards only after the device has confirmed it (Section 8).

5. Automation Rules

A rule watches one field and compares each new value with a threshold — for example "when kitchen/temperature is greater than 30". When the condition is true it can write a value to another field, send a push notification, send an email, or any combination. Rules are created with the Rule widget on a dashboard.

When a rule acts

• The action value is written on every new value that meets the condition. If the temperature stays above 30 and a new reading arrives every 10 seconds, the target field is written every 10 seconds.
• Alerts are sent only when the condition becomes true — the change from false to true. While it stays true, no more alerts are sent. When a value no longer meets the condition, the rule re-arms.
• "Notify every" silences alerts that come too close together. If a value keeps crossing the threshold back and forth, alerts within the chosen interval are skipped. The event is still recorded in the automation log, marked as silenced.

6. Scripts

Scripts run your own JavaScript on the server. They read one or more input fields, calculate, and write results to output fields. Open them from a dashboard: Tools → Scripts. Full reference: Scripts guide.

Two execution modes

Input and output mapping

A script sees fields only through its mapping table. Each row links a script variable to a field:

• IN — the field's latest value (and its time) is available to the script as read-only input.
• OUT — the script can write a result to the field.
• Trigger (IN rows) — a new value on this field starts the script. Two extra options per trigger:
  • only on change — start only when the value differs from the previous one;
  • trigger from Device / Dashboard / Scheduler — start only for values from the ticked sources. With all ticked (the default), every source except rules can start the script.
• Publish (OUT rows) — also send the written value to the field's MQTT subscribers.

Safety limits

Each run takes place in an isolated sandbox and is stopped after 50 ms. When one script's output starts another script, the chain can be at most five scripts long; beyond that, scripts are not started. A script only runs when it is both active and ready.

7. Schedulers

A scheduler writes a fixed ON or OFF value to one field at set times — no conditions, no code. It is added with the Scheduler widget on a dashboard, and each event can repeat:

• weekly — at a time on the chosen days of the week, e.g. every weekday at 07:30;
• annually — on the same day and month every year;
• once — on a specific date; the event switches itself off after it fires.

Times follow the dashboard's time zone. With "Publish via MQTT" on, the value is also sent to the field's subscribers, so a relay can switch at the scheduled time.

Scheduler values enter the hub with source SCHEDULER and can trigger scripts, rules and HTTP Requests, exactly like values from a device.

8. Commands That Wait for Confirmation

Normally a command from a dashboard, rule, script or scheduler is saved and shown as soon as it is sent. On a field with command confirmation turned on, the platform waits for proof that the device actually carried it out:

1. The command is sent to the device via MQTT — nothing else happens yet.
2. The device carries it out and publishes the same value back on the same topic.
3. The echo arrives as a normal MQTT value and goes through the full hub: saved, shown on dashboards, published to {field}/state, and able to trigger scripts, rules and HTTP Requests.
4. If no echo arrives within the field's timeout, the command is marked as not confirmed and the dashboard shows it.

This way the database and your automations always reflect what the device really did, not what it was asked to do. Setup and firmware examples: Confirmed commands.

9. The Processing Order

Every value that reaches the hub goes through these steps, always in this order:

10. Loop Prevention: How the Platform Protects Itself

The danger in any automation platform is an endless loop: a value triggers a script, which writes a value that triggers the script again, forever — filling the database and wasting server resources. Virtuino Cloud stops loops at four levels.

Level 1 — Separate MQTT channels

The platform only listens on the channel clients publish to and only sends on the channel subscribers read (Section 3). Its own MQTT messages can never come back to it as new values.

Level 2 — Echo detection

Many devices answer a command by publishing the same value back. Without protection, that echo would be forwarded to subscribers as a new command, the device would echo it again, and so on. So when a device sends back exactly the value it was just sent — within 3 seconds, or within the confirmation timeout for fields that wait for confirmation — the value is saved as usual but not forwarded again.

Level 3 — Source rules

The source tag limits what a value may trigger:

• A value written by a Rule triggers nothing — no rules, scripts, HTTP Requests or JSON Splitter.
• A value stored by an HTTP Request (or sent through the HTTP API) does not start HTTP Requests, so a request can never call itself.
• Script trigger inputs can be limited to chosen sources (trigger from, Section 6).

Level 4 — Chain length limit

Scripts may start other scripts, and the JSON Splitter's values may start scripts, but every link adds one step to the chain. After five steps, no more scripts or splitters are started — whatever the conditions.

11. Common Problems & How to Solve Them

12. Quick Reference: Source Tags

Every stored value keeps its source tag — you can see it in the Data Monitor. It decides what the value may trigger and when it goes out via MQTT.

With trigger from narrowed on a script input, only the ticked sources start that script: Device means MQTT and HTTP, plus DASHBOARD and SCHEDULER as ticked.

---

Virtuino Cloud Platform — Data Flow & Automation Architecture Guide