Calculated channels

Compute values from other channels with an Arc expression.

A calculated channel computes its values from other channels with an Arc expression. Use a calculated channel to:

• Scale or convert a sensor value, such as volts to pressure.
• Combine sensors, such as the pressure drop across a filter.
• Compare redundant sensors.
• Set a flag when a condition is true, for alarms and warnings.

How calculated channels work

Synnax does not store the values of a calculated channel. It computes them when you stream or read the channel, and it stops when nothing uses the channel.

• Past data -> you can read a calculated channel over a past time range. Synnax computes the values from the stored data of the inputs, so each input must have data in that range.
• Edits -> because Synnax stores no values, an edit also changes all past data. If you change pressure * 3 to pressure * 10, all of the data shows pressure * 10.
• Samples -> the expression runs once for each new sample of any input, after every input has at least one sample. Each channel name gives one value, and an input with no new sample gives its last value.
• Data type -> Synnax gets the data type from the value that the expression returns. return 1 gives an int64 channel, and return 1.0 gives a float64 channel.
• Index -> Synnax creates a virtual index channel named <name>_time for each calculated channel.
• Chains -> a calculated channel can use other calculated channels as inputs. A chain cannot loop back to itself.

Create a calculated channel

import synnax as sy

pressure_drop = client.channels.create(
    name="filter_pressure_drop",
    expression="return inlet_pressure - outlet_pressure",
)

avg_pressure = client.channels.create(
    name="avg_tank_pressure",
    expression="return tank_pressure",
    operations=[
        sy.channel.Operation(type="avg", duration=10 * sy.TimeSpan.SECOND),
    ],
)

import { DataType, TimeSpan } from "@synnaxlabs/client";

const pressureDrop = await client.channels.create({
  name: "filter_pressure_drop",
  dataType: DataType.FLOAT64,
  expression: "return inlet_pressure - outlet_pressure",
});

const avgPressure = await client.channels.create({
  name: "avg_tank_pressure",
  dataType: DataType.FLOAT64,
  expression: "return tank_pressure",
  operations: [{ type: "avg", duration: TimeSpan.seconds(10) }],
});

Edit a calculated channel

pressure_drop.expression = "return (inlet_pressure - outlet_pressure) * 0.0689"
client.channels.create(pressure_drop)

await client.channels.create({
  ...pressureDrop.payload,
  expression: "return (inlet_pressure - outlet_pressure) * 0.0689",
});

Write an expression

An expression is the body of an Arc function. Refer to channels by name, and return the value of the calculated channel. An expression can have many statements.

drop := inlet_pressure - outlet_pressure
return drop * 0.0689

Use an if statement to set a flag:

if tank_pressure > 500.0 {
    return 1
}
return 0

The Arc reference describes operators, variables, and if statements.

Use inputs that share an index

Synnax pairs the samples of the input channels in the order that they arrive. It does not match them by time. When the inputs share an index, each pair of samples has the same timestamp. When the inputs have different indexes, a pair can have samples from different times. For correct results, use inputs that share an index.

Operations

An operation keeps a value across many samples, such as the maximum since a reset. It applies to the result of the expression.

min, max, and avg give one output sample for each group of input samples that Synnax receives, not one for each input sample. They reset in two ways:

• Window -> the operation resets at the end of each window. A 10-second window gives the average of each 10-second period, not a moving average, and a window of 0 never resets.
• Reset channel -> the operation resets when a boolean reset channel receives true. A schematic button or an Arc automation can write to the reset channel.

derivative has no window and no reset channel.

Reset example

A max operation on tank_pressure, with a reset channel. Each line is one group of input samples:

At 10.1 s, the reset channel receives true, and the maximum resets. The operation starts again from the current value, 75.

Operation examples

When you read past data, Synnax receives the samples in different groups than it did live. The output of min, max, and avg can then be different from the live output.

Troubleshooting

• The channel shows an error icon in the toolbar.

  Cause

  The expression is not correct, or it uses a channel that does not exist.

  Fix

  Hover over the icon to see the error, then correct the expression. The error clears when a channel with the missing name exists.

• A line plot shows no values.

  Cause

  One input has never had a sample. The expression runs only after every input has at least one sample.

  Fix

  Write at least one sample to each input.

• A past time range shows no values.

  Cause

  One input has no data in that time range.

  Fix

  Select a time range in which every input has data.

• The values look wrong or shifted in time.

  Cause

  The inputs have different indexes.

  Fix

  Use inputs that share an index. See use inputs that share an index.

• The data type is int64, not float64.

  Cause

  The expression returns an integer.

  Fix

  Write numbers with a decimal point, such as 2.0.

• channel "<name>_time" already exists and cannot serve as the index for a calculated channelchannel "<name>_time" in the same request cannot serve as the index for calculated channel "<name>"

  Cause

  A channel named <name>_time exists and is not a virtual index.

  Fix

  Rename or delete that channel.

• calculated channels cannot specify an index manually

  Cause

  You set an index.

  Fix

  Remove the index setting. Synnax creates the index.

Calculated channel properties lists each property that you can set.