Documentation

Linker EnergyAI Platform Guide

Comprehensive reference for EnergyAI — the industrial Energy Management System for PV + BESS + grid optimization. Dashboards, analytics, device integration, KPI formulas, and API reference in one place.

1. Getting Started

Platform overview, quick start, and system requirements

Platform Overview

EnergyAI is an industrial Energy Management System (EMS) designed for facilities with photovoltaic (PV) generation, battery energy storage (BESS), and grid interconnection. It collects real-time data from Modbus field devices, runs formula-based KPI calculations, and provides AI-powered optimization to minimize energy costs while maximizing renewable self-consumption.

Key capabilities:

  • Real-time Modbus RTU/TCP polling from 13+ device types (meters, inverters, BESS, EV chargers, HVAC)
  • Formula Engine Language (FEL) for live KPI computation with windowed aggregations
  • Five optimization strategies: max_savings, max_profit, max_reserve, self_consumption, peak_shave
  • AI agent with ReAct loop for natural-language analysis, reporting, and anomaly detection
  • Day-ahead market (RDN) integration with ENTSO-E and OREE price feeds
  • Role-based dashboards for Energy Managers, CEOs, and Operations Directors
  • InfluxDB 3 time-series storage with hot/cold tiering

Quick Start

Follow these steps to get oriented in the platform after your administrator has provisioned your account:

  1. Log in at https://app.wattmasters.uk/ using your email and password. Your session token is valid for 24 hours.
  2. Select an Object from the sidebar. An object represents a physical site or facility (e.g., "Factory Kyiv-1").
  3. The Dashboard Overview page loads automatically, showing system status cards, active alarms, and quick-access navigation to all platform areas.
  4. Explore the Energy Balance page for real-time generation/consumption/grid/BESS power flows.
  5. Open Analytics to view cross-asset filters, AI analysis results, and predictive forecasts.
  6. Check Settings to review KPI definitions, EMS policies, and your user role permissions.

System Requirements

ItemDescription
BrowserChrome 120+, Firefox 121+, Safari 17+, Edge 120+
ScreenMinimum 1280x720; optimized for 1920x1080 and above
NetworkStable connection with <200ms latency to the server
AuthenticationEmail/password; session token stored in secure HTTP-only cookie
MobileResponsive layout works on tablets; limited support on phones

2. Dashboard Guide

Role-based views for monitoring and decision-making

Dashboard Overview

The Dashboard Overview is the landing page after selecting an object. It provides a high-level summary of the facility's operational status with quick-access cards to each platform area. Status indicators show device connectivity (online/offline counts), active alarm count with severity breakdown, and the current EMS operating mode.

The overview includes a miniature energy flow diagram showing PV generation, consumption, grid import/export, and BESS charge/discharge at a glance.

Energy Manager Dashboard

Designed for on-site energy managers, this dashboard surfaces operational KPIs as large cards with trend sparklines. Each KPI card shows the current value, the 7-day trend, and a color-coded status indicator (green/amber/red).

Key KPI cards displayed:

  • Solar Self-Consumption (%) — PV energy used on-site vs exported
  • Solar Coverage (%) — fraction of load met by PV alone
  • Renewable Share (%) — total renewable contribution to consumption
  • Peak Demand Reduction (%) — grid peak shaved by BESS/EMS
  • BESS Round-Trip Efficiency (%) — charge-to-discharge losses
  • Power Factor (cos phi) — reactive power health indicator
  • Energy Intensity (kWh/unit) — production efficiency
  • EMS Savings (%) — cost reduction vs no-optimization baseline

CEO Executive Dashboard

A financial and operational summary for executives. Shows cumulative savings (UAH), BESS ROI, EMS ROI, CO2 reduction, and energy cost share of COGS. All values are computed from the KPI Constants configured per object. Charts include monthly savings trend, year-to-date cumulative savings, and a scenario comparison bar chart.

The Scenario Report widget compares the fixed-tariff baseline against the RDN+BESS optimized total, showing the savings delta in both absolute UAH and percentage terms.

Director Console

Operations directors use this console to review and approve optimization plans before they are activated. The console shows pending plans with their expected savings, risk assessment, and affected assets. Directors can approve, reject, or request modifications to each plan.

The approval workflow is logged in the immutable audit trail, capturing the director's identity, timestamp, and decision rationale for compliance purposes.

Energy Balance

Real-time visualization of the facility's energy flows. The Energy Balance page displays power values for each energy source and sink:

ItemDescription
GenerationTotal PV output (kW instantaneous, kWh cumulative)
ConsumptionTotal site load at the main distribution board
Grid ImportPower drawn from the utility when generation + BESS cannot cover load
Grid ExportSurplus power injected into the grid when generation exceeds demand
BESS ChargePower flowing into the battery (positive direction)
BESS DischargePower flowing out of the battery to serve load
State of ChargeBattery level as a percentage of usable capacity (10-90% typical)
Self-SufficiencyPercentage of load met by on-site sources

A Sankey-style flow diagram links sources to sinks. Historical mode allows scrubbing through the past 24h, 7d, or 30d with 1-minute resolution.

Market (RDN)

Displays day-ahead electricity market prices from the RDN (Rynok na Dobu Napered). Prices are shown as a 24-hour bar chart with the current hour highlighted. Price data can be sourced from ENTSO-E Transparency Platform, OREE (Ukraine), or Nord Pool.

The market view also shows the current EUR/UAH exchange rate (from NBU) and the effective import tariff. This data feeds into the EMS optimization engine for BESS charge/discharge scheduling against price signals.

3. Analytics

Cross-asset analysis, forecasting, and AI-generated reports

Analytics Overview

The Analytics Overview provides cross-asset filtering with multi-dimensional analysis. Users can select time ranges, asset groups, and KPI metrics to build custom views. The AI analysis engine runs anomaly detection, correlation analysis, and pattern recognition across selected data streams.

Available analysis modes:

  • Time Series Comparison — overlay multiple KPIs on a shared timeline
  • Correlation Matrix — discover relationships between operational parameters
  • Anomaly Detection — AI-flagged deviations from learned baselines
  • Predictive Forecast — ML-based projection of KPI trajectories (7-day horizon)
  • Benchmark Analysis — compare current performance against historical periods

Energy Forecast

PV generation prediction and day-ahead market (DAM) sell/charge scheduling. The forecast engine uses weather data (irradiance, temperature, cloud cover) combined with historical PV output to predict generation for the next 24-48 hours.

The DAM schedule optimizer uses the PV forecast and RDN price curve to determine optimal BESS charge/discharge windows. It outputs an hourly dispatch schedule that maximizes arbitrage revenue while respecting battery cycle limits and minimum SOC constraints.

ItemDescription
PV Forecast Endpointforecast.pvForecast(session, objectId, horizonHours)
DAM Schedule Endpointforecast.damSchedule(session, objectId, date)
Forecast Accuracy Target85-95% (MAPE-based)
Update FrequencyEvery 6 hours with latest weather data

AI Reports

Automated markdown report generation powered by the AI agent. Each report is structured into 8 sections that cover all aspects of the facility's energy performance:

  1. Executive Summary — high-level findings and key metrics
  2. Energy Balance Analysis — generation, consumption, import/export breakdown
  3. Scenario Comparison — fixed-tariff baseline vs optimized results
  4. Optimization Performance — strategy effectiveness and savings attribution
  5. KPI Dashboard — all computed KPIs with trend analysis
  6. Forecast Accuracy — predicted vs actual generation/consumption
  7. Alarm & Incident Summary — alarm frequency, response times, root causes
  8. Recommendations — AI-generated action items for improvement

Reports are generated via the report.generateReport endpoint. The AI agent fills template tokens with live data from all platform subsystems, then composes narrative analysis using the ReAct loop.

4. Optimization

Strategies, scenario comparison, and loss attribution

Optimization Plan

The optimization engine supports five strategies, each tuned for different operational priorities. The selected strategy determines how the EMS dispatches BESS, shifts loads, and schedules grid interaction:

ItemDescription
max_savings Minimize total energy cost by maximizing self-consumption and shifting imports to off-peak hours
max_profit Maximize revenue from grid export during high-price RDN hours while maintaining site supply
max_reserve Keep BESS at high SOC for backup power, only discharging during grid outages or extreme peaks
self_cons Maximize solar self-consumption ratio by aggressively charging BESS during PV surplus periods
peak_shave Flatten the demand profile to stay below contracted power limits and avoid demand charges

Each strategy produces a 24-hour dispatch plan with hourly BESS setpoints, load shift recommendations, and expected savings. Plans require director approval before activation (see Director Console).

Scenario Report

The Scenario Report compares two energy cost scenarios side by side:

  • Fixed-Tariff Baseline — total cost if all energy was imported from the grid at the contracted flat tariff. Formula: consumption_kWh x import_tariff.
  • RDN+BESS Optimized — actual cost after EMS optimization: reduced imports via self-consumption, BESS arbitrage against RDN prices, and export revenue credits.

The delta between scenarios represents the total value of the EMS. The report breaks down savings into components: self-consumption credit, BESS shift credit (peak-to-off-peak arbitrage), and export earnings.

Human-Factor Report

Loss attribution analysis that identifies where human decisions (or lack thereof) caused energy waste or missed optimization opportunities. The report categorizes losses into:

  • Manual Override Losses — costs incurred when operators overrode EMS recommendations
  • Delayed Response — energy wasted during the gap between alarm trigger and acknowledgment
  • Scheduling Gaps — periods where load shifting was possible but not executed
  • Idle Consumption — standby loads during non-production hours that could have been shed

Each loss category shows the UAH impact, percentage of total energy cost, and specific timestamps of the events. This provides accountability without blame, enabling data-driven process improvement.

5. Assets & Devices

Asset management, IoT device integration, and Modbus registers

Assets Overview

Assets represent physical equipment at a facility: PV arrays, BESS units, transformers, distribution boards, HVAC systems, and EV chargers. Each asset card shows the asset name, type, rated capacity, current operating status, and the number of IoT devices attached to it.

Assets are organized in a tree hierarchy using an adjacency-list model. Root assets are top-level equipment (e.g., a PV plant), and child assets are sub-components (e.g., individual string inverters). The tree is fetched via asset.listForObject and assembled client-side.

Assets Analytics

Per-asset time series with channel breakdown. Select an asset to see all its measurement channels (voltage, current, power, energy, temperature) plotted on a shared timeline. The channel selector allows toggling individual parameters.

Aggregation intervals: 1-minute (live), 15-minute, 1-hour, and 1-day. Data is sourced from InfluxDB 3 with automatic hot/cold tiering. Export to CSV is available for any visible time range.

Assets Control

Operating mode management and direct command buttons for controllable assets. Each asset shows its current mode (Auto/Manual/Maintenance/Off) and provides mode-change controls subject to RBAC permissions.

For BESS assets, additional controls include forced charge/discharge, SOC target adjustment, and emergency shutdown. For EV chargers, the interface shows session state and allows current limit adjustment. All commands are dispatched through the iot.sendCommand endpoint and logged to the audit trail.

IoT Devices

The platform supports 13 Modbus device templates, each with a predefined register map. Devices are polled via Modbus RTU (RS-485) or Modbus TCP at configurable intervals. Supported device types:

  • Acrel ADW300 — 3-phase wireless energy meter (32 registers)
  • Pilot PMAC211 — 4-circuit multi-channel power meter (40 registers)
  • Deye HV 3-Phase — hybrid inverter with PV + BESS (27 registers)
  • SMA Tripower — 3-phase string PV inverter (6 registers)
  • Solis Hybrid — single-phase PV + BESS inverter (6 registers)
  • Huawei SUN2000 — commercial 3-phase string inverter (6 registers)
  • Schneider iEM3100 — 1-phase residential meter (6 registers)
  • Eastron SDM630 — 3-phase commercial meter (7 registers)
  • Phoenix EV Charger — AC charger per IEC 61851 (5 registers)
  • Weather Station — temperature, humidity, irradiance, wind (6 registers)
  • Carrier Chiller — HVAC chiller monitor (5 registers)
  • ABB Transformer — oil/winding temperature and load monitor (5 registers)
  • Smart Breaker — single-circuit on/off with metering (5 registers)

Devices are auto-discovered when a template is assigned, or can be manually configured with custom register maps. Each device shows connectivity status (online/offline), last poll timestamp, and communication error rate.

Device Detail

The device detail page shows a register table with Modbus addresses, data types, scale factors, engineering units, and live values. Registers are grouped by function (voltage, current, power, energy, status) and update in real-time as new polling cycles complete.

Each register row displays: register name, Modbus address (4xxxx or 3xxxx), data type (uint16/int16/uint32/int32), scale factor, unit, OAP code (if mapped), and the last polled value with timestamp. See the Device Templates section below for complete register maps of all 13 templates.

6. Settings

KPI configuration, EMS policies, roles, and personalization

KPI Definitions

The formula editor allows creating and editing KPI definitions using FEL (Formula Engine Language) expressions. Each KPI definition includes a unique kpiId, display name, unit, formula expression, and optional alert thresholds.

FEL supports standard arithmetic, trigonometric functions, conditional expressions, and windowed aggregations (avg, sum, min, max over configurable time windows). Formulas reference node values using path syntax (e.g., /data/meter/U * /data/meter/I).

Definitions are managed via the kpiDefinition endpoint: list, getByKpiId, upsert, and deleteByKpiId. A seedMvp method bootstraps the standard KPI set for new objects.

KPI Constants

Per-object business parameters that feed into KPI formulas. These are numeric values that change infrequently (annually or per contract renewal) and are set by administrators:

ItemDescription
Grid CO2 Emission Factort CO2/MWh — carbon intensity of grid electricity
BESS InvestmentUAH — total CAPEX for battery storage system
Annual BESS ValueUAH/year — yearly economic value from BESS operations
EMS InvestmentUAH — total CAPEX for the Energy Management System
Annual EMS SavingsUAH/year — yearly cost savings from EMS optimization
Total Electricity CostUAH/year — annual electricity expenditure
Total COGSUAH/year — Cost of Goods Sold (denominator for energy cost share)
Production Unitsunits — total output for energy intensity calculation
Total Uptime Hourshours/year — equipment operational time (for MTBF)
Total Calendar Hourshours/year — typically 8760
Equipment Failuresevents/year — unplanned failure count
Total Downtime Hourshours/year — cumulative unplanned downtime
Incidents per Yearevents/year — safety/operational incident count
Automated Actionscount — EMS-executed control actions
Total Actionscount — all control actions (auto + manual)

EMS Policies

Automated reaction rules that trigger when monitored KPI scores cross configured thresholds. Each policy defines: a unique policyId, the target KPI or node path, condition expression, action to execute, and priority level.

Example policies: "If BESS SOC drops below 15%, switch to max_reserve mode", "If grid import exceeds 90% of contracted power, activate peak_shave strategy", "If PV forecast shows surplus, pre-charge BESS to 90% before peak hours".

Policies are managed via emsPolicy.list, emsPolicy.upsert, and emsPolicy.deleteByPolicyId endpoints.

Roles & Users

The platform uses role-based access control (RBAC) with four predefined roles:

ItemDescription
Admin Full access to all features, settings, user management, and device configuration
Operator Can view all dashboards, acknowledge alarms, and execute approved control commands
ViewerRead-only access to dashboards, analytics, and reports
DirectorViewer permissions plus ability to approve/reject optimization plans

Users are provisioned by administrators. Each user is assigned to one or more objects and inherits role permissions for those objects only.

Personalization

Users can customize their experience through the personalization settings:

  • Theme — light or dark mode (dark is default for control room environments)
  • Categories — show/hide sidebar navigation categories based on role needs
  • Layout — compact or comfortable spacing for dashboard cards
  • Dashboard Default — choose which dashboard loads after object selection
  • Notification Preferences — email and push notification settings per alarm severity

7. KPI Reference

All 56 KPI definitions with units, ranges, and formulas. Generated from HelpContent entries.

KPI Constants

Business parameters configured per object. These values are inputs to KPI calculations, not computed metrics themselves.

KPIDescriptionUnitRangeFormula
Grid CO2 Emission Factor Average carbon intensity of grid electricity in your region. Used to calculate CO2 reduction from renewable self-consumption. t CO2/MWh 0.4-1.2 --
BESS Investment Total capital expenditure for the battery energy storage system. Includes equipment, installation, and commissioning costs. UAH -- --
Annual BESS Value Yearly economic value generated by the battery storage system through peak-shaving, energy arbitrage, and grid services revenue. UAH/year 10-30% of BESS investment --
EMS Investment Total capital expenditure for the Energy Management System. Covers hardware, software licenses, integration, and deployment. UAH -- --
Annual EMS Savings Yearly cost savings attributable to the Energy Management System through load optimization, peak shaving, and tariff arbitrage. UAH/year -- --
Total Electricity Cost Annual electricity expenditure including energy charges, demand charges, transmission fees, and applicable taxes. UAH/year -- --
Total COGS Cost of Goods Sold per year. Used to compute energy cost share. UAH/year -- --
Production Units per Period Total output units produced during the reporting period. Denominator for Energy Intensity. units -- --
Total Uptime Hours Cumulative hours that critical equipment was operational. Used for Availability and MTBF. hours/year 8000-8760 --
Total Calendar Hours Total hours in the reporting period (8760 for a non-leap year). hours/year 8760 --
Equipment Failures Number of unplanned equipment failure events. Used to compute MTBF. events/year -- --
Total Downtime Cumulative hours of unplanned downtime caused by equipment failures. Used for MTTR. hours/year -- --
Incidents per Year Total number of safety or operational incidents. events/year -- --
Automated Actions Count Number of control actions executed automatically by the EMS. actions -- --
Total Actions Count Sum of all control actions (automated + manual). actions -- auto_actions + manual_actions

Dashboard KPIs

Computed metrics displayed on the Energy Manager and CEO Executive dashboards.

KPIDescriptionUnitRangeFormula
Solar Self-Consumption Percentage of PV generation consumed on-site vs exported to grid. % 60-95% 100 x sum(min(PV, Load)) / sum(PV generation)
Solar Coverage Fraction of total site consumption met directly by PV generation. % 20-60% 100 x sum(min(PV, Load)) / sum(Load)
Renewable Share Total renewable energy as a share of total consumption. % 30-80% 100 x (PV self-consumed + BESS renewable discharge) / Load
Peak Demand Reduction Reduction of grid peak demand achieved by the EMS. % 10-40% 100 x (baseline_peak - actual_peak) / baseline_peak
BESS Round-Trip Efficiency Energy delivered by the battery divided by energy charged into it. % 85-95% 100 x sum(discharge_kWh) / sum(charge_kWh)
Power Factor Ratio of real power to apparent power. cos phi 0.92-1.0 P (kW) / S (kVA)
THD Voltage Total Harmonic Distortion of the supply voltage (harmonics to the 40th, LV). % < 8% (EN 50160) --
Reactive Energy Ratio Reactive energy consumed relative to active energy. % < 40% 100 x kVArh / kWh
Energy Cost Share Electricity costs as a percentage of total COGS. % 5-30% 100 x electricity_cost_uah / cogs_uah
Energy Intensity Energy consumed per unit of output. kWh/unit Industry-specific sum(consumption_kWh) / production_units
EMS Savings Percentage cost reduction vs no-optimization baseline. % 8-25% 100 x (baseline_cost - actual_cost) / baseline_cost
System Availability Fraction of calendar time equipment was operational. % 95-99.9% 100 x uptime_hours / total_time_hours
MTBF Mean Time Between Failures. hours -- total_uptime_hours / failure_count
MTTR Mean Time To Repair. hours -- total_downtime_hours / failure_count
BESS ROI Return on Investment for the Battery Energy Storage System. % -- 100 x annual_bess_value_uah / invest_bess_uah
EMS ROI Return on Investment for the Energy Management System. % -- 100 x annual_savings_uah / invest_ems_uah
CO2 Reduction Tonnes of CO2 avoided by displacing grid imports with renewables. t CO2 -- grid_emission_factor x (self_consumed_kWh + bess_renewable_kWh) / 1000
EMS Automation Rate Share of control actions executed automatically. % 70-95% 100 x auto_actions / all_actions
Forecast Accuracy How closely the day-ahead forecast matches actual metered values. % 85-95% 100 - MAPE
Alarm Response Time Average time from alarm trigger to operator acknowledgment. minutes < 15 min --
Department Peak Demand Maximum instantaneous power draw of a department. kW -- --
Department Energy per Unit Energy consumption of a department divided by its output. kWh/unit -- department_kWh / department_output_units
Idle Energy Ratio Energy consumed during non-production periods as a share of total. % 5-20% 100 x idle_period_kWh / total_kWh
Night Consumption Share Energy consumed between 22:00-06:00 as percentage of daily total. % 10-35% 100 x night_kWh / daily_total_kWh

Scenario Report Fields

KPIDescriptionUnitRangeFormula
Fixed-Tariff Baseline Total cost if all energy was imported at the fixed import tariff. UAH -- sum(consumption_kWh) x import_tariff
Optimized Total Cost Actual energy cost after EMS optimization. UAH -- residual_import x tariff - export_earnings - bess_credit
Savings Percentage Relative cost reduction from baseline to optimized scenario. % -- 100 x (baseline - optimized) / baseline
Total Consumption Aggregate energy consumed by all loads during the reporting period. kWh -- --
BESS Shift Credit Cost saving from discharging battery during expensive peak hours. UAH -- sum(shifted_kWh) x (peak_tariff - off_peak_tariff)
Import Tariff Contracted electricity import price per kWh. UAH/kWh -- --

Market Fields

KPIDescriptionUnitRangeFormula
RDN Day-Ahead Price Hourly electricity price on the day-ahead market (RDN). EUR/MWh or UAH/MWh -- --
Market Data Source Provider of day-ahead and intraday market price feeds. -- -- --
EUR/UAH Exchange Rate Currency conversion rate for EUR-denominated market prices. UAH per 1 EUR -- --

Energy Balance Fields

KPIDescriptionUnitRangeFormula
Generation Total power output from all on-site generation sources. kW / kWh -- --
Consumption Total site electrical load. kW / kWh -- --
Grid Import Power drawn from the utility grid. kW / kWh -- --
Grid Export Surplus power injected back into the grid. kW / kWh -- --
State of Charge (SOC) Current battery charge level. % 10-90% --
Self-Sufficiency Percentage of consumption met by on-site generation. % -- 100 x min(generation, consumption) / consumption
Peak Load Maximum instantaneous power demand recorded. kW -- --
Grid Deviation Current grid import relative to contracted permitted power. % -- 100 x (import_kW - permitted_kW) / permitted_kW

8. Device Templates

Modbus register maps for all 13 supported device types

Acrel ADW300 — 3-Phase Wireless Energy Meter

Template: adw300 | Registers: 32 | Protocol: Modbus RTU (FC03)

Full 3-phase power analysis meter with phase/line voltages, currents, active/reactive/apparent power per phase and total, power factor per phase and total, frequency, and energy counters (forward, reverse, reactive).

NameAddressTypeScaleUnitDescription
va 40021 uint16 0.1 V Phase A voltage
vb 40022 uint16 0.1 V Phase B voltage
vc 40023 uint16 0.1 V Phase C voltage
vab 40024 uint16 0.1 V Line voltage A-B
vbc 40025 uint16 0.1 V Line voltage B-C
vca 40026 uint16 0.1 V Line voltage C-A
ia 40027 uint16 0.01 A Phase A current
ib 40028 uint16 0.01 A Phase B current
ic 40029 uint16 0.01 A Phase C current
in 40030 uint16 0.01 A Neutral current
pa 40031 int32 1.0 W Phase A active power
pb 40033 int32 1.0 W Phase B active power
pc 40035 int32 1.0 W Phase C active power
p 40037 int32 1.0 W Total active power
qa 40039 int32 1.0 VAr Phase A reactive power
qb 40041 int32 1.0 VAr Phase B reactive power
qc 40043 int32 1.0 VAr Phase C reactive power
q 40045 int32 1.0 VAr Total reactive power
sa 40047 int32 1.0 VA Phase A apparent power
sb 40049 int32 1.0 VA Phase B apparent power
sc 40051 int32 1.0 VA Phase C apparent power
s 40053 int32 1.0 VA Total apparent power
pfa 40055 int16 0.001 -- Phase A power factor
pfb 40056 int16 0.001 -- Phase B power factor
pfc 40057 int16 0.001 -- Phase C power factor
pf 40058 int16 0.001 -- Total power factor
freq 40060 uint16 0.01 Hz Grid frequency
e 40061 uint32 1.0 Wh Net energy
e_fwd 40063 uint32 1.0 Wh Forward (import) energy
e_rev 40065 uint32 1.0 Wh Reverse (export) energy
er_fwd 40067 uint32 1.0 VArh Forward reactive energy
er_rev 40069 uint32 1.0 VArh Reverse reactive energy

Pilot PMAC211 — 4-Circuit Multi-Channel Power Meter

Template: pmac211 | Registers: 40 | Protocol: Modbus RTU (FC03)

Single shared 3-phase voltage input with 4 independent CT circuit inputs. Each circuit measures current, active/reactive power, power factor, apparent power, and energy. Shared measurements include 3-phase voltages and frequency.

NameAddressTypeScaleUnitDescription
va 40001 uint16 0.1 V Shared phase A voltage
vb 40002 uint16 0.1 V Shared phase B voltage
vc 40003 uint16 0.1 V Shared phase C voltage
freq 40010 uint16 0.01 Hz Shared frequency
c1_ia 40011 uint16 0.1 A Circuit 1 phase A current
c1_ib 40012 uint16 0.1 A Circuit 1 phase B current
c1_ic 40013 uint16 0.1 A Circuit 1 phase C current
c1_p 40051 int32 0.1 W Circuit 1 active power
c1_q 40083 int32 0.1 VAr Circuit 1 reactive power
c1_pf 40103 uint16 0.001 -- Circuit 1 power factor
c1_s 40131 uint32 0.1 VA Circuit 1 apparent power
c1_e 40225 uint32 100.0 Wh Circuit 1 energy
c1_er 40289 uint32 100.0 VArh Circuit 1 reactive energy
c2_ia 40014 uint16 0.1 A Circuit 2 phase A current
c2_ib 40015 uint16 0.1 A Circuit 2 phase B current
c2_ic 40016 uint16 0.1 A Circuit 2 phase C current
c2_p 40053 int32 0.1 W Circuit 2 active power
c2_q 40085 int32 0.1 VAr Circuit 2 reactive power
c2_pf 40104 uint16 0.001 -- Circuit 2 power factor
c2_s 40133 uint32 0.1 VA Circuit 2 apparent power
c2_e 40227 uint32 100.0 Wh Circuit 2 energy
c2_er 40291 uint32 100.0 VArh Circuit 2 reactive energy
c3_ia 40017 uint16 0.1 A Circuit 3 phase A current
c3_ib 40018 uint16 0.1 A Circuit 3 phase B current
c3_ic 40019 uint16 0.1 A Circuit 3 phase C current
c3_p 40055 int32 0.1 W Circuit 3 active power
c3_q 40087 int32 0.1 VAr Circuit 3 reactive power
c3_pf 40105 uint16 0.001 -- Circuit 3 power factor
c3_s 40135 uint32 0.1 VA Circuit 3 apparent power
c3_e 40229 uint32 100.0 Wh Circuit 3 energy
c3_er 40293 uint32 100.0 VArh Circuit 3 reactive energy
c4_ia 40020 uint16 0.1 A Circuit 4 phase A current
c4_ib 40021 uint16 0.1 A Circuit 4 phase B current
c4_ic 40022 uint16 0.1 A Circuit 4 phase C current
c4_p 40057 int32 0.1 W Circuit 4 active power
c4_q 40089 int32 0.1 VAr Circuit 4 reactive power
c4_pf 40106 uint16 0.001 -- Circuit 4 power factor
c4_s 40137 uint32 0.1 VA Circuit 4 apparent power
c4_e 40231 uint32 100.0 Wh Circuit 4 energy
c4_er 40295 uint32 100.0 VArh Circuit 4 reactive energy

Deye HV 3-Phase — Hybrid Inverter (PV + BESS)

Template: deye_hv_3ph (version 10) | Registers: 79, 44 documented below | Protocol: Modbus TCP over the DTU, FC03 reads, FC16 writes

Three-phase hybrid inverter, protocol V100. Grid-side and inverter-side voltages/currents, four PV strings, battery, the load side, and the energy counters. Signed grid power: positive = import, negative = export.

This table was four template versions stale until 2026-09-08 — it still carried the PV strings at 40279-40282 and 40187/40188, registers the hardware abandoned. Every address, type and scale below is now taken from linker_flutter/test/fixtures/template_points.tsv, which is generated from the runner templates and pinned to them by a test on each side. The writable control block (switch_on_off, active_power_pct, the charge/discharge limits, energy_pattern, max_sell_power, zero_export_power, solar_sell, tou_enable and the 24 TOU slot registers) is deliberately not listed here: it is documented where it is operated, in the TOU runbook.

NameAddressTypeScaleUnitDescription
run_state 40501 uint16 1.0 -- Inverter run state
grid_va 40599 uint16 0.1 V Grid phase A voltage
grid_vb 40600 uint16 0.1 V Grid phase B voltage
grid_vc 40601 uint16 0.1 V Grid phase C voltage
grid_ia 40611 int16 0.01 A Grid phase A current
grid_ib 40612 int16 0.01 A Grid phase B current
grid_ic 40613 int16 0.01 A Grid phase C current
freq 40610 uint16 0.01 Hz Grid frequency
inv_va 40628 uint16 0.1 V Inverter phase A voltage
inv_vb 40629 uint16 0.1 V Inverter phase B voltage
inv_vc 40630 uint16 0.1 V Inverter phase C voltage
inv_ia 40631 int16 0.01 A Inverter phase A current
inv_ib 40632 int16 0.01 A Inverter phase B current
inv_ic 40633 int16 0.01 A Inverter phase C current
pv1_v 40677 uint16 0.1 V PV string 1 voltage
pv1_i 40678 uint16 0.1 A PV string 1 current
pv1_p 40673 uint16 10.0 W PV string 1 power (v10: x10 W, not the vendor’s 1 W)
pv2_v 40679 uint16 0.1 V PV string 2 voltage
pv2_i 40680 uint16 0.1 A PV string 2 current
pv2_p 40674 uint16 10.0 W PV string 2 power (v10: x10 W, not the vendor’s 1 W)
pv3_v 40681 uint16 0.1 V PV string 3 voltage
pv3_i 40682 uint16 0.1 A PV string 3 current
pv3_p 40675 uint16 10.0 W PV string 3 power (v10: x10 W, not the vendor’s 1 W)
pv4_v 40683 uint16 0.1 V PV string 4 voltage
pv4_i 40684 uint16 0.1 A PV string 4 current
pv4_p 40676 uint16 10.0 W PV string 4 power (v10: x10 W, not the vendor’s 1 W)
bat_v 40588 uint16 0.01 V Battery voltage
bat_i 40592 int16 0.01 A Battery current
bess_soc 40589 uint16 1.0 % Battery state of charge
bess_power 40591 int16 1.0 W Battery power (+charge/-discharge)
p_grid_total 40608 int16 1.0 W Total grid power (signed: + import, - export)
inv_active_total 40637 int16 1.0 W Inverter own total AC output power
load_pa 40651 int16 1.0 W Load side phase A power
load_pb 40652 int16 1.0 W Load side phase B power
load_pc 40653 int16 1.0 W Load side phase C power
p_load_total 40654 int16 1.0 W Total active power on the load side (signed)
e_today_buy 40521 uint16 0.1 kWh Energy bought from the grid today
e_today_sell 40522 uint16 0.1 kWh Energy sold to the grid today
e_total_buy 40523 uint32 0.1 kWh Energy bought from the grid, lifetime
e_total_sell 40525 uint32 0.1 kWh Energy sold to the grid, lifetime
e_today_load 40527 int16 0.1 kWh Load energy today (signed: negative on a parallel master)
e_total_load 40528 int32 0.1 kWh Load energy lifetime (signed)
e_today_pv 40530 uint16 100.0 Wh PV generation today (v10: was idx 501, which reads a flat zero)
e_total_pv 40535 uint32 100.0 Wh PV generation lifetime (v10: was idx 504/505, a flat zero)

SMA Tripower — 3-Phase String PV Inverter

Template: sma_tripower | Registers: 6 | Protocol: Modbus RTU (FC03)

NameAddressTypeScaleUnitDescription
ac_power_total 40001 uint32 1.0 W Total AC output power
dc_power_pv1 40003 uint32 1.0 W DC power from PV string 1
dc_power_pv2 40005 uint32 1.0 W DC power from PV string 2
energy_today 40007 uint32 100.0 Wh Energy generated today
freq 40009 uint16 0.01 Hz Grid frequency
inverter_status 40010 uint16 1.0 -- Inverter status code

Solis Hybrid — Single-Phase PV + BESS Inverter

Template: solis_hybrid | Registers: 6 | Protocol: Modbus RTU (FC04)

NameAddressTypeScaleUnitDescription
pv_power 33057 uint32 1.0 W PV generation power
bess_soc 33139 uint16 1.0 % Battery state of charge
bess_power 33149 int16 1.0 W Battery power (signed)
grid_power 33130 int16 1.0 W Grid power (signed)
load_power 33147 uint32 1.0 W Total load power
energy_today 33035 uint16 100.0 Wh Energy generated today

Huawei SUN2000 — Commercial 3-Phase String Inverter

Template: huawei_sun2000 | Registers: 6 | Protocol: Modbus RTU (FC03)

NameAddressTypeScaleUnitDescription
pv1_p 32064 int32 1.0 W PV string 1 power
pv2_p 32066 int32 1.0 W PV string 2 power
ac_power_total 32080 int32 1.0 W Total AC output power
efficiency 32086 uint16 0.01 % Inverter efficiency
temp_inverter 32087 int16 0.1 C Inverter temperature
energy_total 32106 uint32 100.0 Wh Total energy generated

Schneider iEM3100 — 1-Phase Residential Meter

Template: schneider_iem3100 | Registers: 6 | Protocol: Modbus RTU (FC03)

NameAddressTypeScaleUnitDescription
voltage 40129 uint32 0.001 V Line voltage
current 40139 uint32 0.001 A Line current
power 40149 int32 1.0 W Active power
power_factor 40159 int16 0.001 -- Power factor
freq 40169 uint16 0.1 Hz Grid frequency
energy_active 40187 uint32 1000.0 Wh Active energy import

Eastron SDM630 — 3-Phase Commercial Meter

Template: eastron_sdm630 | Registers: 7 | Protocol: Modbus RTU (FC04)

NameAddressTypeScaleUnitDescription
va 40001 uint32 1.0 V Phase A voltage
vb 40003 uint32 1.0 V Phase B voltage
vc 40005 uint32 1.0 V Phase C voltage
ia 40007 uint32 1.0 A Phase A current
power_total 40053 int32 1.0 W Total active power
energy_import 40073 uint32 1000.0 Wh Energy import total
energy_export 40075 uint32 1000.0 Wh Energy export total

Phoenix EV Charger — AC Charger (IEC 61851)

Template: phoenix_ev_charger | Registers: 5 | Protocol: Modbus RTU (FC03)

CP state codes per IEC 61851: 0=disconnected, 1=connected, 2=charging, 3=ventilation required, 4=error.

NameAddressTypeScaleUnitDescription
session_state 40001 uint16 1.0 -- CP session state (IEC 61851)
session_power 40002 uint32 1.0 W Active session power
session_energy 40004 uint32 100.0 Wh Session energy delivered
session_duration_s 40006 uint32 1.0 s Session duration
max_current 40008 uint16 0.1 A Maximum charging current

Weather Station — Environmental Sensors

Template: weather_station | Registers: 6 | Protocol: Modbus RTU (FC04)

NameAddressTypeScaleUnitDescription
temp_c 40001 int16 0.1 C Ambient temperature
humidity_pct 40002 uint16 0.1 % Relative humidity
irradiance 40003 uint16 1.0 W/m2 Solar irradiance (GHI)
wind_speed 40004 uint16 0.1 m/s Wind speed
wind_dir 40005 uint16 1.0 deg Wind direction
rainfall_mm 40006 uint16 0.1 mm Rainfall accumulation

Carrier Chiller — HVAC Chiller Monitor

Template: carrier_chiller | Registers: 5 | Protocol: Modbus RTU (FC03)

Compressor status codes: 0=off, 1=starting, 2=running, 3=alarm.

NameAddressTypeScaleUnitDescription
load_kw 40001 uint32 1.0 W Chiller electrical load
supply_temp_c 40003 int16 0.1 C Chilled water supply temperature
return_temp_c 40004 int16 0.1 C Chilled water return temperature
compressor_status 40005 uint16 1.0 -- Compressor status code
runtime_hours 40006 uint32 1.0 h Compressor runtime hours

ABB Transformer — Oil/Winding Temperature and Load Monitor

Template: abb_transformer | Registers: 5 | Protocol: Modbus RTU (FC04)

NameAddressTypeScaleUnitDescription
oil_temp_c 40001 int16 0.1 C Transformer oil temperature
winding_temp_c 40002 int16 0.1 C Winding temperature
load_kva 40003 uint32 1.0 VA Load apparent power
load_pct 40005 uint16 0.1 % Load as percentage of rated capacity
tap_position 40006 int16 1.0 -- On-load tap changer position

Smart Breaker — Single-Circuit On/Off with Metering

Template: smart_breaker | Registers: 5 | Protocol: Modbus RTU (FC03)

State codes: 0=open, 1=closed, 2=tripped. Includes a writable action (set_state) for remote control.

NameAddressTypeScaleUnitDescription
state 40001 uint16 1.0 -- Breaker state (0=open, 1=closed, 2=tripped)
current 40002 uint16 0.1 A Circuit current
power 40003 uint32 1.0 W Circuit power
trip_count 40005 uint16 1.0 -- Cumulative trip count
temperature_c 40006 int16 0.1 C Breaker temperature

9. API Reference

Serverpod endpoint method signatures for all platform APIs

auth

Authentication and session management.

MethodReturnsDescription
login(session, String email, String password) Future<String> Authenticate and return a session token
validateToken(session, String token) Future<bool> Check if a session token is still valid

object

CRUD operations for facility objects.

MethodReturnsDescription
list(session) Future<List<LinkerObject>> List all objects
getById(session, int id) Future<LinkerObject?> Get a single object by ID
create(session, LinkerObject input) Future<LinkerObject> Create a new object
update(session, LinkerObject input) Future<LinkerObject?> Update an existing object
delete(session, int id) Future<bool> Delete an object by ID
getMnemo(session, int objectId) Future<String?> Get mnemonic schema for an object
setMnemo(session, int objectId, String schema) Future<bool> Set mnemonic schema for an object
listForUser(session, String userId) Future<List<LinkerObject>> List objects accessible to a user
setControlMode(session, int objectId, ...) Future<LinkerObject?> Set the EMS control mode for an object
validateForOptimization(session, int objectId) Future<String> Validate object readiness for optimization

asset

Asset hierarchy management.

MethodReturnsDescription
getById(session, int id) Future<LinkerAsset?> Get a single asset by ID
listForObject(session, int objectId) Future<List<LinkerAsset>> All assets for an object (flat list)
listChildren(session, int parentAssetId) Future<List<LinkerAsset>> Direct children of a parent asset
listRoots(session, int objectId) Future<List<LinkerAsset>> Root-level assets (no parent)

iot

Modbus device management and real-time readings.

MethodReturnsDescription
getDevices(session) Future<List<ModbusDevice>> List all registered Modbus devices
getLatestReadings(session, String deviceId) Future<Map<String, dynamic>> Latest polled values for a device
getEventLogs(session, String deviceId) Future<List<DeviceEventLog>> Device event log (connect/disconnect/error)
deleteDevice(session, String deviceId) Future<bool> Remove a device from the registry
updateDevice(session, String deviceId, ...) Future<bool> Update device configuration
sendCommand(session, String deviceId, ...) Future<bool> Send a control command to a device

energy

Energy profile queries from InfluxDB time-series storage.

MethodReturnsDescription
queryEnergyProfile(session, int objectId, ...) Future<String> Query energy profile for a time range (JSON)
queryEnergyProfileComparison(session, int objectId, ...) Future<String> Compare two energy profile periods (JSON)

ceo

Executive dashboard data: savings, scenario reports, energy flows.

MethodReturnsDescription
queryCumulativeSavings(session, int objectId, ...) Future<String> Cumulative savings over a time range (JSON)
querySavingsBreakdown(session, int objectId, ...) Future<String> Savings breakdown by component (JSON)
queryEnergyFlowCurrent(session, int objectId) Future<String> Current energy flow snapshot (JSON)
queryConsumptionStructure(session, int objectId, ...) Future<String> Consumption structure breakdown (JSON)
queryScenarioReport(session, int objectId, ...) Future<String> Scenario comparison report (JSON)

market

Day-ahead electricity market price data.

MethodReturnsDescription
listSources(session) Future<List<LinkerMarketSource>> List configured market data sources
getSource(session, int id) Future<LinkerMarketSource?> Get a single market source by ID
upsertSource(session, LinkerMarketSource source) Future<LinkerMarketSource> Create or update a market source
deleteSource(session, int id) Future<bool> Delete a market source
next24h(session, int sourceId) Future<List<LinkerMarketPrice>> Next 24 hours of market prices
priceNow(session, int sourceId) Future<LinkerMarketPrice?> Current hour market price
importCsv(session, int sourceId, String csvData) Future<String> Bulk import prices from CSV data

report

AI-generated analytical report system.

MethodReturnsDescription
listSections(session) Future<String> List available report sections (JSON)
generateReport(session, int objectId, ...) Future<String> Generate full AI report with all 8 sections (markdown)

predictive

ML-based KPI prediction.

MethodReturnsDescription
predictKpi(session, int objectId, String kpiId, ...) Future<String> Predict KPI trajectory for a given horizon (JSON)

forecast

PV generation forecast and day-ahead market scheduling.

MethodReturnsDescription
pvForecast(session, int objectId, int horizonHours) Future<String> PV generation forecast for given horizon (JSON)
damSchedule(session, int objectId, String date) Future<String> Optimal BESS dispatch schedule against DAM prices (JSON)

kpiDefinition

FEL formula management for computed KPIs.

MethodReturnsDescription
list(session, int objectId) Future<List<LinkerKpiDefinition>> List all KPI definitions for an object
getByKpiId(session, String kpiId) Future<LinkerKpiDefinition?> Get a KPI definition by its ID
upsert(session, LinkerKpiDefinition def) Future<LinkerKpiDefinition> Create or update a KPI definition
deleteByKpiId(session, String kpiId) Future<bool> Delete a KPI definition
seedMvp(session) Future<int> Bootstrap standard KPI set for new objects

emsPolicy

Automated EMS reaction rules.

MethodReturnsDescription
list(session, int objectId) Future<List<LinkerEmsPolicy>> List all EMS policies for an object
getByPolicyId(session, String policyId) Future<LinkerEmsPolicy?> Get a policy by its ID
upsert(session, LinkerEmsPolicy policy) Future<LinkerEmsPolicy> Create or update a policy
deleteByPolicyId(session, String policyId) Future<bool> Delete a policy