> For the complete documentation index, see [llms.txt](https://renewables.docs.helinplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://renewables.docs.helinplatform.com/sgm-product-docs/reference-docs/udm.md). # Universal Data Model Helin Universal Data Model, the SunSpec-based naming convention and model catalogue used for metric URIs in the SGM API. The **Helin Universal Data Model** is the naming convention and data schema SGM uses to label every measurement and control point coming off a site. It's based on the [SunSpec Alliance](https://sunspec.org/) standards, extended for Helin's data platform. If you've used the SGM API and seen metric keys like `CUST/ST01/PL01/SYS01/INVR/AB4321/W` in the `metrics_v2` field of `GET /sites/{site_id}`, that's UDM. This page explains what each segment means and which models the data points come from. {% hint style="info" %} You don't need to author UDM data to use SGM. The platform produces UDM-formatted metrics for you. This reference is here so you can interpret what you receive. {% endhint %} ## Asset naming convention Every measurement is identified by a hierarchical URI: ``` Client / SiteID / PlantID / system / DeviceCat_ID / measurement ``` A real-world example: ``` SRRL / DSV090 / PL01 / SYS01 / INVR_BB8383 / TmpCab ``` Read top-to-bottom that's: customer **SRRL**, site **DSV090**, plant **PL01**, system **SYS01**, the inverter (`INVR`) with serial **BB8383**, reporting cabinet temperature (`TmpCab`). Each segment has a fixed role: | Segment | Example | Meaning | | ------------- | -------------- | ----------------------------------------------------------------- | | Client | `SRRL`, `CUST` | Customer or organisation owning the data | | SiteID | `DSV090` | Physical site identifier | | PlantID | `PL01` | Plant within the site (a site may have multiple plants) | | system | `SYS01` | System identifier within the plant | | DeviceCat\_ID | `INVR_BB8383` | Device category abbreviation + unique device ID | | measurement | `TmpCab` | The specific measurement point (defined by a SunSpec model field) | ## Device categories UDM uses these short codes for the `DeviceCat` segment: | Code | Category | What it represents | | ------ | ------------------------ | ----------------------------------------- | | `INVR` | Inverter | Solar inverter or power conversion system | | `LOGG` | Logger | Data acquisition / logging system | | `PMTR` | Power Meter | Electrical measurement device | | `EMS` | Energy Management System | Control system for energy optimisation | | `EVSE` | EV Charger | Electric vehicle charging infrastructure | | `BESS` | Battery Energy Storage | Energy storage solution | | `MEAS` | Measurement | Generic measurement device | | `RIO` | Remote I/O | Remote input/output module | ## SunSpec models in use UDM 1.0 covers the 12 SunSpec models that map cleanly onto SGM's supported asset types. Each model is identified by a numeric ID and defines a fixed set of measurements with strict units and scale factors. ### Inverter models | Model | Name | Use | | ----- | --------------------- | ------------------------------------------------------ | | 101 | Single-phase inverter | Residential / small commercial PV | | 102 | Split-phase inverter | North American 240V split-phase systems | | 103 | Three-phase inverter | Most commercial and utility-scale PV (the common case) | ### Inverter control models | Model | Name | Use | | ----- | ------------------------------------------------ | ------------------------------------------------- | | 120 | Inverter Controls Nameplate Ratings | Static capability declarations (W, VA, A ratings) | | 121 | Inverter Controls Basic Settings | Configurable limits (`WMax`, `VRef`, etc.) | | 122 | Inverter Controls Extended Measurements & Status | PV/storage/ECP connection status | | 123 | Immediate Inverter Controls | Real-time control commands | | 124 | Basic Storage Controls | Charge state, battery voltage, charge/discharge | ### Other models | Model | Name | Use | | ----- | ------------------------- | -------------------------------------------------- | | 203 | Three-phase wye meter | Site grid meters (the source of `metrics_v2` data) | | 302 | Irradiance | GHI, POAI, diffuse irradiance | | 307 | Base meteorological model | Temperature, humidity, pressure, wind | | 701 | DER Measure AC | Site wide AC measurements | | 702 | DER Capacity | Maximum ratings, nameplate limits | | 704 | DER Control AC | Power setpoints | | 801 | Battery base model | BESS state | | 802 | Battery base model | BESS measurements and capacity ratings | ## Datapoints Each device category, `DeviceCat` , implements its own set of datapoints. HelinEMS makes a best effort to populate all applicable datapoints based on the information provided by the actual device. These datapoints are designed to cover the most common functionality of each device type. For example, all inverters provide measurements such as voltage, current, and power, regardless of manufacturer. These datapoints are therefore included in the `INVR` data model. Empty datapoints, that is, datapoints that have missing values because they are not known, are omitted from the payload. #### Inverter / Logger (\`INVR\` / \`LOGG\`) | Datapoint | Description | Unit | Type | | --------------- | -------------------------------------------------------------- | ---- | ------- | | `St` | Overall device state (`OK`, `INFO`, `WARNING`, `FAULT`) | - | Text | | `EvtWarn` | Device reports a warning or a fault | - | Flag | | `EvtFault` | Device reports a fault | - | Flag | | `EvtCommsFault` | Communication with the device has failed (Modbus devices only) | - | Flag | | `W` | Power | W | Numeric | | `VA` | Apparent power | VA | Numeric | | `VAr` | Reactive power | VAr | Numeric | | `PF` | Power factor, as a magnitude in `0`–`1` | - | Numeric | | `Hz` | Grid frequency | Hz | Numeric | | `WH` | Produced energy | Wh | Numeric | | `A` | Current | A | Numeric | | `AphA` | Current on phase 1 | A | Numeric | | `AphB` | Current on phase 2 | A | Numeric | | `AphC` | Current on phase 3 | A | Numeric | | `V` | Voltage | V | Numeric | | `PhVphA` | Voltage on phase 1 | V | Numeric | | `PhVphB` | Voltage on phase 2 | V | Numeric | | `PhVphC` | Voltage on phase 3 | V | Numeric | | `WMax` | Rated maximum power the device can produce, per its nameplate | W | Numeric | | `WLimit` | Production limit currently applied to the device (curtailment) | W | Numeric | | `WMaxLimPct` | `WLimit` as a percentage of `WMax`, `0`–`100` | % | Numeric | | `W_SF` | Scale factor for power datapoints | - | Numeric | | `WH_SF` | Scale factor for energy datapoints | - | Numeric | | `VAr_SF` | Scale factor for reactive power datapoints | - | Numeric | | `Hz_SF` | Scale factor for frequency datapoints | - | Numeric | | `V_SF` | Scale factor for voltage datapoints | - | Numeric | | `A_SF` | Scale factor for current datapoints | - | Numeric | #### Battery Energy Storage System (\`BESS\`) | Datapoint | Description | Unit | Type | | ------------------ | ---------------------------------------------------------------- | ---- | ------- | | `A_SF` | Scale factor for current datapoints | - | Numeric | | `A` | Current | A | Numeric | | `AphA` | Current on phase 1 | A | Numeric | | `AphB` | Current on phase 2 | A | Numeric | | `AphC` | Current on phase 3 | A | Numeric | | `ChaWH` | Charged energy | Wh | Numeric | | `DisChaWH` | Discharged energy | Wh | Numeric | | `EvtCommsFault` | Communication with the device has failed (Modbus devices only) | - | Flag | | `EvtFault` | Device reports a fault | - | Flag | | `EvtWarn` | Device reports a warning or a fault | - | Flag | | `Hz_SF` | Scale factor for frequency datapoints | - | Numeric | | `Hz` | Grid frequency | Hz | Numeric | | `PhVphA` | Voltage on phase 1 | V | Numeric | | `PhVphB` | Voltage on phase 2 | V | Numeric | | `PhVphC` | Voltage on phase 3 | V | Numeric | | `SoC` | State of charge | % | Numeric | | `St` | Overall device state (`OK`, `INFO`, `WARNING`, `FAULT`) | - | Text | | `V_SF` | Scale factor for voltage datapoints | - | Numeric | | `V` | Voltage | V | Numeric | | `VA` | Apparent power | VA | Numeric | | `VAr_SF` | Scale factor for reactive power datapoints | - | Numeric | | `VAr` | Reactive power | VAr | Numeric | | `W_SF` | Scale factor for power datapoints | - | Numeric | | `W` | Power; positive = discharging, negative = charging | W | Numeric | | `WH_SF` | Scale factor for energy datapoints | - | Numeric | | `WphA` | Power on phase 1 | W | Numeric | | `WphB` | Power on phase 2 | W | Numeric | | `WphC` | Power on phase 3 | W | Numeric | | `VArphA` | Reactive power on phase 1 | VAr | Numeric | | `VArphB` | Reactive power on phase 2 | VAr | Numeric | | `VArphC` | Reactive power on phase 3 | VAr | Numeric | | `EvtPowerSetFault` | Applying the power setpoint failed | - | Flag | | `DisChaWMax` | Maximum discharge power currently allowed by the battery | W | Numeric | | `ChaWMax` | Maximum charge power currently allowed by the battery (negative) | W | Numeric | | `DisChaWReq` | Requested discharge power | W | Numeric | | `ChaWReq` | Requested charge power (negative) | W | Numeric | | `DisChaVArReq` | Requested reactive power while discharging | VAr | Numeric | | `ChaVArReq` | Requested reactive power while charging (negative) | VAr | Numeric | | `DisChaWReqphA` | Requested discharge power on phase 1 | W | Numeric | | `DisChaWReqphB` | Requested discharge power on phase 2 | W | Numeric | | `DisChaWReqphC` | Requested discharge power on phase 3 | W | Numeric | | `ChaWReqphA` | Requested charge power on phase 1 (negative) | W | Numeric | | `ChaWReqphB` | Requested charge power on phase 2 (negative) | W | Numeric | | `ChaWReqphC` | Requested charge power on phase 3 (negative) | W | Numeric | | `DisChaVArReqphA` | Requested reactive power while discharging on phase 1 | VAr | Numeric | | `DisChaVArReqphB` | Requested reactive power while discharging on phase 2 | VAr | Numeric | | `DisChaVArReqphC` | Requested reactive power while discharging on phase 3 | VAr | Numeric | | `ChaVArReqphA` | Requested reactive power while charging on phase 1 (negative) | VAr | Numeric | | `ChaVArReqphB` | Requested reactive power while charging on phase 2 (negative) | VAr | Numeric | | `ChaVArReqphC` | Requested reactive power while charging on phase 3 (negative) | VAr | Numeric | #### EV Charging Station (\`EVSE\`) | Datapoint | Description | Unit | Type | | --------------- | ------------------------------------------------------- | ---- | ------- | | `St` | Overall device state (`OK`, `INFO`, `WARNING`, `FAULT`) | - | Text | | `EvtWarn` | Device reports a warning or a fault | - | Flag | | `EvtFault` | Device reports a fault | - | Flag | | `EvtCommsFault` | Communication with the charging station has failed | - | Flag | | `W` | Charging power | W | Numeric | | `VA` | Apparent power | VA | Numeric | | `VAr` | Reactive power | VAr | Numeric | | `Hz` | Grid frequency | Hz | Numeric | | `ConsWH` | Consumed energy | Wh | Numeric | | `A` | Current | A | Numeric | | `AphA` | Current on phase 1 | A | Numeric | | `AphB` | Current on phase 2 | A | Numeric | | `AphC` | Current on phase 3 | A | Numeric | | `V` | Voltage | V | Numeric | | `PhVphA` | Voltage on phase 1 | V | Numeric | | `PhVphB` | Voltage on phase 2 | V | Numeric | | `PhVphC` | Voltage on phase 3 | V | Numeric | | `WMin` | Minimum charging power the hardware supports | W | Numeric | | `WMax` | Maximum charging power the hardware supports | W | Numeric | | `W_SF` | Scale factor for power datapoints | - | Numeric | | `WH_SF` | Scale factor for energy datapoints | - | Numeric | | `VAr_SF` | Scale factor for reactive power datapoints | - | Numeric | | `Hz_SF` | Scale factor for frequency datapoints | - | Numeric | | `V_SF` | Scale factor for voltage datapoints | - | Numeric | | `A_SF` | Scale factor for current datapoints | - | Numeric | | `WReq` | Requested charging power | W | Numeric | | `WLimit` | Applied charging power limit | W | Numeric | | `WhLimit` | Charging session energy limit | Wh | Numeric | #### Power Meter (\`PMTR\`) | Datapoint | Description | Unit | Type | | --------------- | -------------------------------------------------------------- | ---- | ------- | | `St` | Overall device state (`OK`, `INFO`, `WARNING`, `FAULT`) | - | Text | | `EvtWarn` | Device reports a warning or a fault | - | Flag | | `EvtFault` | Device reports a fault | - | Flag | | `EvtCommsFault` | Communication with the device has failed (Modbus devices only) | - | Flag | | `W` | Power | W | Numeric | | `VA` | Apparent power | VA | Numeric | | `VAr` | Reactive power | VAr | Numeric | | `WphA` | Power on phase 1 | W | Numeric | | `WphB` | Power on phase 2 | W | Numeric | | `WphC` | Power on phase 3 | W | Numeric | | `VArphA` | Reactive power on phase 1 | VAr | Numeric | | `VArphB` | Reactive power on phase 2 | VAr | Numeric | | `VArphC` | Reactive power on phase 3 | VAr | Numeric | | `Hz` | Grid frequency | Hz | Numeric | | `WH` | Produced energy | Wh | Numeric | | `ProdWHphA` | Produced energy on phase 1 | Wh | Numeric | | `ProdWHphB` | Produced energy on phase 2 | Wh | Numeric | | `ProdWHphC` | Produced energy on phase 3 | Wh | Numeric | | `ConsWH` | Consumed energy | Wh | Numeric | | `ConsWHphA` | Consumed energy on phase 1 | Wh | Numeric | | `ConsWHphB` | Consumed energy on phase 2 | Wh | Numeric | | `ConsWHphC` | Consumed energy on phase 3 | Wh | Numeric | | `A` | Current | A | Numeric | | `AphA` | Current on phase 1 | A | Numeric | | `AphB` | Current on phase 2 | A | Numeric | | `AphC` | Current on phase 3 | A | Numeric | | `V` | Voltage | V | Numeric | | `PhVphA` | Voltage on phase 1 | V | Numeric | | `PhVphB` | Voltage on phase 2 | V | Numeric | | `PhVphC` | Voltage on phase 3 | V | Numeric | | `W_SF` | Scale factor for power datapoints | - | Numeric | | `WH_SF` | Scale factor for energy datapoints | - | Numeric | | `VAr_SF` | Scale factor for reactive power datapoints | - | Numeric | | `Hz_SF` | Scale factor for frequency datapoints | - | Numeric | | `V_SF` | Scale factor for voltage datapoints | - | Numeric | | `A_SF` | Scale factor for current datapoints | - | Numeric | #### HelinEMS (\`EMS\`) | Datapoint | Description | Unit | Type | | ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ---- | ------- | | `UDMVersion` | Version of the UDM that the data is reported in | - | Text | | `EssSoC` | Average state of charge across all storage systems, capacity-weighted; see Derived values | % | Numeric | | `EssW` | Total storage power; positive = discharging | W | Numeric | | `EssWphA` | Total storage power on phase 1 | W | Numeric | | `EssWphB` | Total storage power on phase 2 | W | Numeric | | `EssWphC` | Total storage power on phase 3 | W | Numeric | | `EssVAr` | Total storage reactive power | VAr | Numeric | | `EssWBat` | Total storage power on the battery side; positive = discharging | W | Numeric | | `EssWMaxDisCha` | **Highest discharge power ever observed** at this site (≥ 0). Not a present limit | W | Numeric | | `EssWMaxCha` | **Highest charge power ever observed** at this site, as a negative value (≤ 0). Not a present limit | W | Numeric | | `EssVAMax` | Total maximum apparent power of all storage systems | VA | Numeric | | `EssWHCap` | Total installed (nameplate) storage capacity | Wh | Numeric | | `EssWHDisCha` | Total energy discharged, cumulative, AC side | Wh | Numeric | | `EssWHCha` | Total energy charged, cumulative, AC side | Wh | Numeric | | `GridMode` | Grid connection state: `ON-GRID`, `OFF-GRID`, or `UNDEFINED` | - | Text | | `GridW` | Power at the grid connection point; positive = import, negative = export | W | Numeric | | `GridWphA` | Grid power on phase 1 | W | Numeric | | `GridWphB` | Grid power on phase 2 | W | Numeric | | `GridWphC` | Grid power on phase 3 | W | Numeric | | `GridWMaxImp` | **Highest import power ever observed** at the grid connection point (≥ 0). Not a contractual limit | W | Numeric | | `GridWMaxExp` | **Highest export power ever observed** at the grid connection point, as a negative value (≤ 0). Not a contractual limit | W | Numeric | | `GridWHImp` | Total energy imported from the grid, cumulative | Wh | Numeric | | `GridWHExp` | Total energy exported to the grid, cumulative | Wh | Numeric | | `GridOffGridTms` | Cumulative time spent off-grid, lifetime counter | s | Numeric | | `ProdW` | Total production power, AC and DC combined | W | Numeric | | `ProdACW` | Total production power measured on the AC side | W | Numeric | | `ProdWphA` | AC production power on phase 1 | W | Numeric | | `ProdWphB` | AC production power on phase 2 | W | Numeric | | `ProdWphC` | AC production power on phase 3 | W | Numeric | | `ProdDCW` | Total production power measured on the DC side | W | Numeric | | `ProdWMax` | Highest production power ever observed at this site; see Extreme-ever values | W | Numeric | | `ProdWUnmngd` | Production power from sources HelinEMS cannot control. Currently equal to `ProdW` | W | Numeric | | `WH` | Total produced energy, AC and DC combined | Wh | Numeric | | `ProdACWH` | Total produced energy measured on the AC side | Wh | Numeric | | `ProdDCWH` | Total produced energy measured on the DC side | Wh | Numeric | | `ConsW` | Total site consumption power | W | Numeric | | `ConsWphA` | Site consumption power on phase 1 | W | Numeric | | `ConsWphB` | Site consumption power on phase 2 | W | Numeric | | `ConsWphC` | Site consumption power on phase 3 | W | Numeric | | `ConsWMax` | Highest consumption power ever observed at this site; see Extreme-ever values | W | Numeric | | `ConsWUnmngd` | `ConsW` minus the metered power of loads HelinEMS actively manages | W | Numeric | | `ConsWH` | Total consumed energy | Wh | Numeric | | `ProdToConsW` | Production power going directly to consumption | W | Numeric | | `ProdToConsWH` | Production energy that went to consumption | Wh | Numeric | | `ProdToGridW` | Production power exported to the grid | W | Numeric | | `ProdToGridWH` | Production energy exported to the grid | Wh | Numeric | | `ProdToEssW` | Production power charging storage | W | Numeric | | `ProdToEssWH` | Production energy that charged storage | Wh | Numeric | | `GridToConsW` | Grid power going to consumption | W | Numeric | | `GridToConsWH` | Grid energy that went to consumption | Wh | Numeric | | `GridToEssW` | Storage charging from the grid. **Signed**: negative = storage exporting to the grid | W | Numeric | | `GridToEssWH` | Grid energy that charged storage | Wh | Numeric | | `EssToConsW` | Storage power going to consumption | W | Numeric | | `EssToConsWH` | Storage energy that went to consumption | Wh | Numeric | | `EssToGridWH` | Storage energy exported to the grid | Wh | Numeric | | `EssDCWHCha` | Energy charged into storage, measured DC-side | Wh | Numeric | | `EssDCWHDisCha` | Energy discharged from storage, measured DC-side | Wh | Numeric | | `ProdWMax` | `ProdW`, highest, ≥ 0 | W | Numeric | | `ConsWMax` | `ConsW`, highest, ≥ 0 | W | Numeric | | `GridWMaxImp` | `GridW`, highest, ≥ 0 | W | Numeric | | `GridWMaxExp` | `GridW`, lowest, ≤ 0 | W | Numeric | | `EssWMaxDisCha` | `EssWBat`, highest, ≥ 0 | W | Numeric | | `EssWMaxCha` | `EssWBat`, lowest, ≤ 0 | W | Numeric | | `EssChaSt` | Storage operating mode: `OFF`, `EMPTY`, `DISCHARGING`, `CHARGING`, `FULL`, `HOLDING`, or `TESTING` | - | Text | | `SelfSuffPct` | Share of consumption covered without importing from the grid, `0`–`100` | % | Numeric | ## Scale factors Every measurement in a SunSpec model has an associated **scale factor**, a small signed integer that tells you how to interpret the raw value. The actual value is calculated as: ``` actual_value = raw_value × 10^(scale_factor) ``` Scale factors apply to families of fields with matching prefixes. A handful of common ones: | Scale factor | Applies to fields starting with | Example | | ------------ | ------------------------------- | --------------------------------------------- | | `A_SF` | `A`, `AphA`, `AphB`, `AphC` | AC current per phase | | `V_SF` | `V*`, `PhV*`, `PPV*` | Voltages (phase-to-neutral, phase-to-phase) | | `W_SF` | `W*` | Active power | | `VA_SF` | `VA*` | Apparent power | | `VAr_SF` | `VAr*` | Reactive power | | `PF_SF` | `PF*` | Power factor | | `Hz_SF` | `Hz*` | Frequency | | `WH_SF` | `WH*` | Energy (Wh, daily/monthly accumulators) | | `Tmp_SF` | `Tmp*` | Temperature (cabinet, heat sink, transformer) | | `DCA_SF` | `DCA*` | DC current | | `DCV_SF` | `DCV*` | DC voltage | | `DCW_SF` | `DCW*` | DC power | **Worked example:** an inverter reports `A = 1534` and `A_SF = -1`. The actual current is: ``` 1534 × 10^(-1) = 153.4 A ``` If you skip applying the scale factor, you'll be off by orders of magnitude. ## Common parameters across models Some fields appear in nearly every model and let you build generic processing pipelines: | Field | Models | Meaning | | ----- | ----------------------- | --------------------------- | | `ID` | All | Model identifier | | `L` | All | Model length (in registers) | | `A` | 101, 102, 103, 203, 802 | Total AC current | | `W` | 101, 102, 103, 203, 802 | Active power | | `Hz` | 101, 102, 103, 203 | Frequency | ## Implementation guidance If you're consuming UDM data: 1. **Always apply scale factors before displaying or processing values.** Skip this step and your numbers are wrong by powers of ten. 2. **Validate against expected ranges.** Any reading outside the device's `min_value`/`max_value` is suspect, usually a scale factor not applied, or a sensor fault. 3. **Handle missing fields gracefully.** Not every device populates every field of its model. Treat missing measurements as "not reported", not as zero. 4. **Use the URI structure to filter.** If you only care about inverter cabinet temperatures, glob on `*/INVR_*/TmpCab`. For the full SunSpec specification including every field of every model, see the [SunSpec Alliance documentation](https://sunspec.org/specifications/). ## Relevant pages

:cube:

Supported assets

Which devices SGM speaks UDM to.

:server:

API: site metrics

Where you receive UDM-formatted measurements (metrics_v2).

:plug:

API: devices

Look up the devices that produce UDM data.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://renewables.docs.helinplatform.com/sgm-product-docs/reference-docs/udm.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.