Energy Advisor - Workflow Engine
The Voltimax.EnergyAdvisor service runs inside the cloud Platform API and evaluates a gateway's workflow whenever the platform receives a telemetry update. It returns the strategy the gateway should execute, which the platform then sends down as a control command. It wraps the RulesEngine NuGet package, which evaluates C# lambda expression strings against a typed input object.
The workflow and its rules are stored per-gateway in PostgreSQL and loaded on each evaluation cycle by RulesEvaluationService.
Evaluation context
Each rule expression is evaluated against a RuleEvaluationContext instance. The context is composed of three sub-objects:
System - site measurements
| Property | Type | Description |
|---|---|---|
System.BatterySoC | double | Battery state of charge (0–100 %). |
System.SolarPower | double | Solar generation in watts. Positive = producing. |
System.GridPower | double | Grid power in watts. Positive = importing, negative = exporting. |
System.BatteryPower | double | Battery power in watts. Positive = charging, negative = discharging. |
Time - temporal state
| Property | Type | Description |
|---|---|---|
Time.CurrentTime | DateTimeOffset | Current timestamp with timezone. |
Time.CurrentHour | int | Hour of day (0–23). |
Time.IsSunset | bool | true at sunset (transition point). |
Time.IsNight | bool | true between sunset and sunrise. |
Time.IsPeakHour | bool | true when the current hour falls inside the gateway's configured peak-tariff window. |
Pricing - electricity market data
| Property | Type | Description |
|---|---|---|
Pricing.CurrentPrice | double | Current spot electricity price (currency per kWh). |
Pricing.AveragePrice | double | Daily average spot price for today. |
Pricing.IsLowPriceHour | bool | true when CurrentPrice < AveragePrice. |
Pricing.IsHighPriceHour | bool | true when CurrentPrice > AveragePrice. |
Pricing.NextHourPrices | List<EpexPrice> | Upcoming hourly prices for look-ahead rules. |
Expression syntax
Rule expressions are C# lambda expression strings without the leading lambda parameter - RulesEngine binds the RuleEvaluationContext as the implicit input. Use standard C# comparison and logical operators.
Supported operators
| Operator | Meaning |
|---|---|
<, <=, >, >= | Numeric comparison |
==, != | Equality |
&& | Logical AND |
|| | Logical OR |
! | Logical NOT |
Examples - from the built-in templates
Battery Protection
// Fire when battery SoC drops below 20 %
"System.BatterySoC < 20"
// Fire when the battery is fully charged
"System.BatterySoC >= 95"Smart Charging
// Charge on low-tariff hours while there is room in the battery
"Pricing.IsLowPriceHour && System.BatterySoC < 80"
// Avoid grid import during peak hours when battery has sufficient charge
"Time.IsPeakHour && System.GridPower > 0 && System.BatterySoC > 20"
// Detect grid import at night
"Time.IsNight && System.GridPower > 0"Solar Optimisation
// Detect surplus: solar is producing, grid is exporting, battery is full
"System.SolarPower > 0 && System.GridPower < 0 && System.BatterySoC >= 95"
// Battery is actively charging from solar
"System.SolarPower > 0 && System.BatteryPower > 0"Peak Demand Management
// Discharge during peak-tariff hours if battery has charge
"Time.IsPeakHour && System.BatterySoC > 30"
// Discharge on high spot price if battery can cover demand
"Pricing.IsHighPriceHour && System.BatterySoC > 40"Combining conditions
Use && freely - expressions are evaluated as a single boolean. There is no nesting syntax; if you need complex branching, use multiple rules in sequence and let the first-match logic handle priority.
Evaluation order and result
Rules are evaluated top-to-bottom. The engine stops at the first rule whose expression evaluates to true and returns that rule's Strategy value as the EvaluationResult.
If no rule matches, no strategy change is issued and the gateway continues on its current setting.
The Strategy enum (defined in Voltimax.Iot.Contracts) maps to gateway operating modes:
| Value | Operating mode |
|---|---|
Strategy.None | No automatic control |
Strategy.NetZero | Net-zero grid import/export |
Strategy.Charge | Actively charge the battery |
Strategy.Discharge | Actively discharge the battery |
Strategy.PeakShaving | Limit peak grid demand |
Built-in templates
The four shipped workflow templates are defined in WorkflowTemplates.cs and are available via GET /workflow/templates. They serve as working starting points that can be applied as-is or customised per gateway.
Operator documentation
See Energy Management for the non-technical overview of workflows and strategies intended for operators.