Calculation

Calculation Executor: Formula-Based Data Transformation

The Calculation Executor enables you to create derived data points by computing values from other data points using mathematical formulas, allowing you to generate new insights from raw sensor data.

Info: This is an Executor node type that can be executed to perform work by the execution of a parent node. When placed as a child of a trigger or another executor, it will automatically run when its parent executes.

Info: This feature uses TargetingNodeMetaData, which means it can be configured to read from data source nodes (like Data Points) and write results to target nodes. This allows for flexible data flow configurations across your automation workflows.

Overview

The Calculation Engine provides a powerful way to transform and combine data from multiple sources using mathematical expressions. Results are computed in real-time and stored in target data points, which can be on any Krill Server node in your mesh network.

Key Features

• Formula-Based Computation: Write mathematical expressions using standard operators
• Multi-Source Support: Reference multiple data points in a single formula
• Variable Substitution: Use data point names as variables in formulas
• Real-Time Evaluation: Calculations execute immediately when triggered
• Remote Targets: Send results to data points on any server in the mesh
• Error Handling: Comprehensive validation and error reporting

Calculation Processing Flow

graph TD
    A[Parent Node Executes] --> B[Calculation Executor Triggered]
    B --> C{Formula Valid?}
    C -->|No| D[Set Error State]
    C -->|Yes| E[Resolve Variable Names]
    E --> F[Fetch Source Data Points]
    F --> G[Substitute Values]
    G --> H[Evaluate Math Expression]
    H --> I{Success?}
    I -->|No| J[Log Error]
    I -->|Yes| K[Create Snapshot]
    K --> L[Update Target Data Point]
    L --> M[Trigger Target's Children]

How It Works

When a calculation executor is triggered:

1. Validation: Checks that a formula is configured
2. Variable Resolution: Identifies data point references in the formula
3. Value Fetching: Retrieves current values from source data points
4. Substitution: Replaces variable names with actual values
5. Evaluation: Computes the mathematical result
6. Target Update: Creates a new snapshot and updates the target data point
7. Propagation: Target data point triggers its own child executors

Formula Syntax

Formulas can include:

• Arithmetic Operators: +, -, *, /, %
• Parentheses: For operation precedence
• Decimal Numbers: 3.14159, 0.5, 100.0
• Data Point References: Use data point names as variables

Example formulas:

Temperature * 1.8 + 32           // Celsius to Fahrenheit
(Pressure1 + Pressure2) / 2      // Average pressure
Flow_Rate * 60                   // Convert per-minute to per-hour

Configuration

Field	Description	Required
formula	Mathematical expression to evaluate	Yes
sources	List of source data point IDs	Yes
targets	List of target data point IDs (typically one)	Yes

Use Cases

• Unit Conversion: Convert between Celsius/Fahrenheit, PSI/Bar, etc.
• Averaging: Calculate average values from multiple sensors
• Rate Calculations: Convert between time units (per-second to per-hour)
• Scaling: Apply calibration factors to sensor readings
• Differential Calculations: Compute differences or deltas
• Complex Formulas: Combine multiple inputs for derived metrics

Example Workflows

Temperature Monitoring with Conversion:

1. Trigger: Cron Timer (every 5 minutes)
2. Executor: Calculation (TempC * 1.8 + 32)
3. Target: Display Data Point in Fahrenheit

Multi-Sensor Averaging:

1. Trigger: Button or Threshold
2. Executor: Calculation ((Sensor1 + Sensor2 + Sensor3) / 3)
3. Target: Average Reading Data Point

Flow Rate Integration:

1. Trigger: DataPoint Update
2. Executor: Calculation (Flow * 3600)
3. Target: Hourly Flow Total

The Calculation Executor is essential for creating sophisticated data pipelines that transform raw sensor readings into actionable information.