Scripts

Scripts run your own JavaScript on the Virtuino Cloud server. A script reads values from one or more fields, does whatever calculation or logic you need, and writes the results to other fields — without changing the firmware of your boards. This guide shows how to set one up, what your code can use, and eleven tested examples you can copy.

1. What a script does

Every script follows the same pattern: read the fields mapped as inputs, calculate, and write to the fields mapped as outputs. Typical jobs:

• Conversion and calibration — turn a raw ADC reading into degrees, litres or bar.
• Control logic — a thermostat, a safety interlock, a pump that depends on several conditions.
• Combining sensors — averages, differences, power from voltage and current.
• Counting and records — running totals, the lowest or highest value, a smoothed reading.
• Supervision — notice that a sensor has gone silent, or that two sensors disagree.

A script's results are ordinary field values: they appear on dashboards, can be sent to boards via MQTT, and can trigger rules — see the Data Flow guide for how they travel through the platform.

2. Creating a script

Scripts belong to a dashboard. Open the dashboard and choose Tools → Scripts.

1. Add script opens the script library. Pick a ready-made script as a starting point.
2. Settings — give it a name and a description, tick active status, and optionally turn on Periodic Execution (Timer) with an interval in seconds.
3. IO mapping — connect fields to the variable names your code uses (Section 3).
4. Edit code — write the code, try it with Run Test, and save.

The icon in front of each script in the list shows its state:

3. IO mapping: connecting fields to variables

A script never names fields in its code. Instead, the mapping table links each field to a short JS variable name. The same code can then be reused with other fields just by changing the mapping. Each row has:

When trg is ticked, two more options appear under the row:

• only on change — start the script only when the value differs from the previous one. A board that repeats the same reading every few seconds then does not run the script each time.
• trigger from: Device / Dashboard / Scheduler — start the script only for values from the ticked sources. Device means values sent via MQTT or HTTP. With all three ticked (the default), any new value starts the script, except values written by a rule.

4. Writing the code: inputs and outputs

Your code sees two objects, named after the JS variables of the mapping:

inputs — what the script reads

Every IN row becomes inputs.<variable> with two properties:

const temp = parseFloat(inputs.temp.value);
if (isNaN(temp)) return;      // no value yet, or not a number

outputs — what the script writes

Assign a value to outputs.<variable> for each OUT row you want to write:

outputs.heater = 1;                        // a number
outputs.status = "OK";                      // or text
outputs.power  = { value: 575.2, time: inputs.amps.time };   // a value with its own time

• Only what you assign is written. An OUT variable that the code leaves untouched — or sets to null — writes nothing, and the field keeps its value. This is how a thermostat "holds" inside its dead band (example 2).
• A value with its own time — { value, time } — is stored with that time instead of the moment the script ran (example 7).
• Use return to stop early. Outputs assigned before the return are still written.

Remembering a value between runs

Every run starts with empty outputs, and variables in the code do not survive from one run to the next. To remember something — a running total, a record, a smoothed value — keep it in a field, and map that field twice, with two different variable names:

The code reads the previous total from inputs.total and writes the new one to outputs.newTotal; the next run reads it back. The IN row of the remembered field must not have trg ticked — otherwise the script would start again from its own output. The mapping refuses that combination. See examples 9–11.

5. When a script runs

A script runs only when it is active and its mapping is complete (green icon).

• On event — as soon as a field marked trg receives a new value that passes its only on change and trigger from options. All other IN variables get their field's latest stored value.
• On timer — with Periodic Execution (Timer) on, every set number of seconds, whether new data arrived or not. All IN variables get their field's latest stored value. If some IN rows are also marked trg, the script runs on those events too.

Each output enters the platform like any other value, tagged with source SCRIPT: it is saved, shown on dashboards, sent via MQTT if pub is ticked, and can trigger rules, HTTP Requests and other scripts. When one script's output starts another script, the chain can be at most five scripts long; after that, no more scripts start. Values written by a rule never start a script. The full picture is in the Data Flow guide.

6. What the code can use, and the limits

Scripts run in an isolated JavaScript sandbox. Available: the whole standard language — Math, JSON, Date, arrays, strings, try/catch, functions — plus console.log(). Not available: network requests, files, timers such as setTimeout, and require or other modules. To fetch data from the internet, use HTTP Requests and let a script process the stored response.

7. Testing and troubleshooting

In the code editor, the Input Simulation panel lists every IN variable with a box for a test value. Press Run Test: the code runs in your browser with those values, and Console Output shows your console.log() lines, the outputs the script would write, or the error it hit. A test writes nothing to your fields, so you can try values freely.

8. Examples

Each example shows its IO mapping and the complete code. The field names are only examples — map your own fields and keep the JS variable names, or change both. trg and pub in the Options column are the checkboxes of the mapping row.

// 0 … 4095 on the ADC  =  -50 … 150 °C on the transmitter
const raw = parseFloat(inputs.raw.value);
if (isNaN(raw)) return;                  // no value yet, or not a number

const celsius = raw * 200 / 4095 - 50;
outputs.celsius = Math.round(celsius * 10) / 10;   // one decimal

const BAND = 0.5;                        // °C above and below the setpoint

const temp     = parseFloat(inputs.temp.value);
const setpoint = parseFloat(inputs.setpoint.value);
if (isNaN(temp) || isNaN(setpoint)) return;

if (temp < setpoint - BAND) {
    outputs.heater = 1;                  // too cold: heater on
} else if (temp > setpoint + BAND) {
    outputs.heater = 0;                  // warm enough: heater off
}
// Inside the band: no output at all, so the heater stays as it is.

const request      = parseFloat(inputs.request.value) === 1;
const estopPressed = parseFloat(inputs.estop.value) === 1;
const pressureHigh = parseFloat(inputs.pressureHigh.value) === 1;

// Run only if everything is safe. A missing input counts as "not requested".
outputs.pump = (request && !estopPressed && !pressureHigh) ? 1 : 0;

const LIMIT = 4.5;                       // allowed difference

const a = parseFloat(inputs.a.value);
const b = parseFloat(inputs.b.value);
if (isNaN(a) || isNaN(b)) return;

const diff = Math.abs(a - b);
outputs.diff  = Math.round(diff * 10) / 10;
outputs.alarm = diff > LIMIT ? 1 : 0;

const MAX_AGE_MIN = 5;

const hasValue = !isNaN(parseFloat(inputs.temp.value));
const ageMin   = (Date.now() - new Date(inputs.temp.time).getTime()) / 60000;

outputs.ok = (hasValue && ageMin < MAX_AGE_MIN) ? 1 : 0;

// Example message: {"temperature": 22.4, "humidity": 61}
let data;
try {
    data = JSON.parse(inputs.payload.value);
} catch (e) {
    console.log('Not valid JSON:', inputs.payload.value);
    return;
}

if (typeof data.temperature === 'number') outputs.temp = data.temperature;
if (typeof data.humidity === 'number')    outputs.hum  = data.humidity;

const volts = parseFloat(inputs.volts.value);
const amps  = parseFloat(inputs.amps.value);
if (isNaN(volts) || isNaN(amps)) return;

outputs.watts = {
    value: Math.round(volts * amps * 10) / 10,
    time:  inputs.amps.time               // same timestamp as the current reading
};

const values = [inputs.t1, inputs.t2, inputs.t3]
    .map(input => parseFloat(input.value))
    .filter(v => !isNaN(v));             // skip sensors without a value

if (values.length === 0) return;

const sum = values.reduce((total, v) => total + v, 0);
outputs.average = Math.round(sum / values.length * 10) / 10;

Examples that remember a value

These three keep their result in a field that is mapped both as IN and as OUT — see Remembering a value between runs.

const liters = parseFloat(inputs.liters.value);
if (isNaN(liters)) return;

let total = parseFloat(inputs.total.value);
if (isNaN(total)) total = 0;             // first run: the total field is still empty

outputs.newTotal = Math.round((total + liters) * 100) / 100;

const temp = parseFloat(inputs.temp.value);
if (isNaN(temp)) return;

const low = parseFloat(inputs.low.value);
if (isNaN(low) || temp < low) {
    outputs.newLow = temp;               // a new record (or the very first value)
}

const K = 0.2;                           // 0…1: smaller = smoother but slower

const raw = parseFloat(inputs.raw.value);
if (isNaN(raw)) return;

const previous = parseFloat(inputs.smooth.value);
const next = isNaN(previous) ? raw : previous + K * (raw - previous);

outputs.newSmooth = Math.round(next * 100) / 100;

Virtuino Cloud — Scripts Guide