Power of Ten Multiplier
espi:powerOfTenMultiplier
Green Button data units are based on international norms as well as regional units. Whenever possible, the units use the most-base level of each unit.
For example, watts (W) are used instead of kilowatts (kW). However, the kilowatt and the kilowatt-hour (kWh) are the typical measurements for billing purposes (for residential and small businesses, at least).
Further, the sent values (value
) are represented as integers in the XML data fields of Green Button outputs—not represented as decimals or as floating-point values.
A power-of-ten multiplier is used to represent that the values being sent are different from the unit of measure.
Cost and Currency Representations and Scaling
Currency has a fixed scaling. To learn about Currency, please visit our Developer page for Currency:
powerOfTenMultiplier
The ESPI standard has a scaling device called the powerOfTenMultiplier
, which as its name implies, handles the adjustment of base units to desired units.
What’s tricky is knowing when the multiplier should be applied.
When a Data Custodian (utility, aggregator, other provider of usage data) loads data into a Green Button output file or stream to share with a consumer or their agent, they include the unit of measure (uom
), the measured or calculated (and then sent) value (value
), and often a multiplier (powerOfTenMultiplier
) to adjust their value to something other than the unit of measure.
For a ReadingType
, a file/stream of usage data may have something like this:1
<content>
<espi:ReadingType>
<espi:accumulationBehaviour>4</espi:accumulationBehaviour> <!-- incremental interval data -->
<espi:commodity>1</espi:commodity> <!-- electricity Secondary Metered -->
<espi:currency>124</espi:currency> <!-- Canadian Dollar (CAD) -->
<espi:dataQualifier>12</espi:dataQualifier> <!-- Normal -->
<espi:flowDirection>1</espi:flowDirection> <!-- forward -->
<espi:intervalLength>300</espi:intervalLength> <!-- five minutes -->
<espi:kind>12</espi:kind> <!-- energy -->
<espi:phase>129</espi:phase> <!-- Phases A to neutral -->
<espi:powerOfTenMultiplier>3</espi:powerOfTenMultiplier> <!-- 10³ -->
<espi:uom>72</espi:uom> <!-- a unit of “Wh” -->
</espi:ReadingType>
</content>
In this example, there are several fields/elements/tags that we’ll use for other examples, so let’s go into them here:
accumulationBehaviour
is set to an enumeration of “4” — which means “incremental interval data”: “The difference between the value at the end of the prescribed interval and the beginning of the interval. This is used for incremental interval data. Note: One common application would be for load profile data, another use might be to report the number of events within an interval (such as the number of equipment energizations within the specified period of time.)”commodity
is set to an enumeration of “1” — which means “electricity Secondary Metered”: “All types of metered quantities. This type of reading comes from the meter and represents a ‘secondary’ metered value.”currency
is set to “124” — which refers to the Canadian Dollar — which you can learn more about on our Cost and Currency page.dataQualifier
is set to “12” — which means “Normal”: “Code describing a salient attribute of Readings of ReadingType.”flowDirection
is set to an enumeration of “1” — which means “forward”: “‘Delivered,’ or ‘Imported’ as defined 61968-2. Forward Active Energy is a positive kWh value as one would naturally expect to find as energy is supplied by the utility and consumed at the service. Forward Reactive Energy is a positive VArh value as one would naturally expect to find in the presence of inductive loading. In polyphase metering, the forward energy register is incremented when the sum of the phase energies is greater than zero.” (where “61968-2” refers to the IEC 61968-2 System interfaces for distribution management – Part 2: Glossary).intervalLength
is set to a value of “300” — which means 300 seconds for the particular interval measurement (five minutes). For most residential applications, this value is usually “3600” (one-hour intervals) for electricity readings that are obtained from smart meters.kind
is set to an enumeration of “12” — which refers to aMeasurementKind
type of “energy” (since currency, temperature, power factors, and other things could be the measured value instead).phase
is set to an enumeration of “129” — which refers to aPhaseCodeKind
type of “AN”: “Phases A to neutral.”powerOfTenMultiplier
is set to a value of “3” — which means the actual value (let’s call it: V) equals the sent value —<espi:value>4321</espi:value>
(let’s call the sent value: VS) — multiplied by ten-to-the-3rd power: V = VS × 103.
We’ll look at an example with a multiplier of “3” … below.uom
(the unit of measure) is set to an enumeration of “72” — which means “Wh”: “Real energy, Watt hours, Wh.”
The
uom
unit is used for the base unit-of-measure for readings ofReadingType
in combination with thepowerOfTenMultiplier
to specify the actual value as it relates to the unit of measure.
Kilowatt-Hours v. Watt-Hours
Using kWh and Wh as examples, it’s easy to see how the value
from the Data Custodian could be sent in different ways but the received actual value will be the same.
✏️ — Before we proceed, please note the below example value of 4321.000 kWh
is being displayed to you in YOUR locale numbering format, therefore you should be reading this number as four thousand, three hundred, twenty-one kilowatt-hours. If you are reading it as something other than that, your locale settings in the browser you are using are set incorrectly.
EXAMPLE…
If a Data Custodian wanted to denote that a consumer used 4321.000 kWh
— which is (four thousand three hundred twenty-one kilowatt-hours) in a given interval, they could send either of the following:
<espi:value>4321</espi:value>
...
<espi:powerOfTenMultiplier>3</espi:powerOfTenMultiplier> <!-- 10³ -->
<espi:uom>72</espi:uom> <!-- a unit of “Wh” -->
or the equivalent:
<espi:value>4321000</espi:value> <!-- value is sent already multiplied -->
...
<espi:powerOfTenMultiplier>0</espi:powerOfTenMultiplier> <!-- 10⁰ ... multiplier not needed -->
<espi:uom>72</espi:uom> <!-- a unit of “Wh” -->
Either one would provide the receiver with an actual value of 4321.000 kWh
(four thousand three hundred twenty-one kilowatt-hours).2
The uom
, however, is Wh (watt-hour) — there is no kWh (kilowatt-hour) option in the Green Button data format. That lack of scaled base values prevents a receiver from having to handle multiple unit types for the same measured quantities of a particular resource. The Third Party needs only to know that the sent value
provided (VS) will be scaled by the powerOfTenMultiplier
to know the actual value (V) in the provided uom
unit type; then, it can be displayed as Wh or kWh, however the application desires.
So, using our example, let’s first show our formula with a powerOfTenMultiplier
of “3” and a sent value
(Vs) of “4321”:
V = VS × 10x
V = 4321 × 103
V = 4321 × 1000
V = 4321000
V = 4321000.000 Wh
(four million three hundred twenty-one thousand watt-hours)
That’s the same as 4321.000 kWh
(four thousand three hundred twenty-one kilowatt-hours).
If we use a powerOfTenMultiplier
of “0” instead with a sent value
(Vs) of “4321000”, we get:
V = VS × 10x
V = 4321000 × 100
V = 4321000 × 1
V = 4321000
V = 4321000.000 Wh
(four million three hundred twenty-one thousand watt-hours)
… the same actual value as above: 4321.000 kWh
(four thousand three hundred twenty-one kilowatt-hours).
Negative Power Factors —
What if the
powerOfTenMultiplier
was ‘−3’ with a sent value
(Vs) of ‘4321000’?
In that case, we would get:
V = VS × 10x
V = 4321000 × 10(−3)
V = 4321000 × 0.001
V = 4321
V = 4321.000 Wh
(four thousand three hundred twenty-one watt-hours)
… a very different actual value from what’s above: 4.321000 kWh
(four and three hundred twenty-one thousandths kilowatt-hours).
The value
field is a 48-bit integer, so this last example shows where the powerOfTenMultiplier
is critical to the value
to accurately express the actual value:
“4.321” cannot be carried in a
value
field because it is not an integer. There can be no decimal in thevalue
field.
Often, the actual scaled value can be more-or-less verified by understanding the value
, the uom
, and the intervalLength
, but out of context it may still be difficult to know if the actual scaled value is correct — especially if it still fits within expectations regardless of scaling direction. When implementing, as a Data Custodian, it is important to be consistent and:
check the output of real data to be sure you are properly conveying what’s actually desired.
Need more help with this? Check-out our Technical Education offerings.
- ^ See the page on Atom & ESPI to understand the “
espi:
” notation herein.
- ^ Because “thousands” and “decimal” placeholders vary in different countries and regions, please note that the examples here use your browser’s LOCALE information to format the example results into a locale-specific representation of numbers. Therefore, in our examples that use a comma for marking thousands and a period (full-stop character) for marking decimals (like this: 9,876.54321 kWh), you may see
9876.54321 kWh
— which isnine thousand eight hundred seventy-six and fifty-four thousand three hundred twenty-one hundred-thousandths
in any case (even if the delimiters are different or it is truncated by your browser).