Energy
What the plant uses and what it costs: kilowatt hours, gas, water, compressed air, and the cost of a unit made, on one screen, pointed at a factory floor. No new hardware and no new protocol. A meter is a tag HotLoop already reads, and this is the bookkeeping on top of it: what the tag counted, kept in the database, priced.
A meter
Section titled “A meter”A meter reads one tag as a quantity used. It has one of two modes.
| Mode | The tag is | What was used is |
|---|---|---|
counter |
a cumulative count: a kWh register, a gas totalizer, a water meter’s pulses | how far it moved, times the meter’s factor |
power |
a rate: kW drawn right now, in W, kW or MW |
the mean of two readings over the time between them |
factor is what one step of a counter is worth in the meter’s unit: 0.001
turns a register in Wh into kWh, 0.01 means a pulse is a hundredth of a cubic
metre. Left out it is 1. A power meter takes no factor: its power_unit and its
unit (Wh, kWh or MWh) say how to convert.
| Kind | For | Usual unit |
|---|---|---|
electricity |
kWh | kWh |
gas |
gas | m³ |
water |
water | m³ |
air |
compressed air | m³ |
heat |
steam, hot water, heat | kWh |
production |
units made | units |
A production meter counts what the line made. It has no tariff, and it is what
the cost of a unit is divided by.
Make one on the Energy screen (New meter) or with POST /api/energy/meters
(see the HTTP API). Only an admin makes, changes or removes a meter
(energy.write); everybody reads (energy.read). The tag must exist and be a
number. If the tag is deleted later the meter says it is waiting, and picks the
tag up again when it is made again.
How it counts
Section titled “How it counts”Every ten seconds the engine reads each meter’s tag from the same cache every screen reads, and works out what each new reading adds. What it adds goes into buckets of 15 minutes, in the database, in the same transaction as the meter’s last reading. So a restart loses nothing, and counts nothing twice.
- A counter adds how far it moved since the last reading, spread over the time between the two readings in proportion to the time in each bucket.
- A counter that goes backwards was reset or replaced. Nothing says how much
was used, so nothing is added: the new value is the new starting point, and the
meter counts the reset (
status.resets). - A counter that kept counting while HotLoop was off. The movement is real and all of it is kept, spread evenly over the gap, and every bucket it touched is marked estimated. A gap is more than ten minutes between two readings.
- A power is the mean of two readings over the time between them. For a gap
of more than ten minutes there is nothing: the meter does not make up a power
for time nobody read, and the gap is counted (
status.gap_seconds). Each bucket says how many of its 900 seconds readings back (covered_seconds), and the screen says “Read for 63% of the period” when a power meter was not read for part of it. A power reading that used nothing still covers its time. - A reading that is bad (the tag’s quality is not good) adds nothing, and the meter says so on its card with the reason. A counter that was unread and comes back counts what it moved meanwhile, as a gap.
- A reading that could not be stored is worked out again on the next tick from the same starting point.
What it costs
Section titled “What it costs”A tariff prices each bucket as it is made: a flat price per unit, and optionally
bands for a time-of-use tariff. A band is from and to on a quarter hour in
the site’s own clock (a to before the from runs past midnight), the days it
holds on (mon to sun, every day when left out), and a price. The first band
that holds at the moment wins; outside every band the flat price holds. A
bucket is priced at the middle of the time each reading covers.
Because the cost is stored with the bucket, a price changed later does not change what last month cost. Changing a meter’s tariff changes what it counts from then on.
currency is a code or a symbol. Costs in two currencies are never added: the
summary has a cost for each.
A demand charge
Section titled “A demand charge”An electricity meter in Wh, kWh or MWh can have a demand_price in its
tariff: what one kilowatt of the plant’s highest quarter hour costs. Over a
window, a bucket’s demand is the kilowatts it averaged (a quarter hour that used
25 kWh averaged 100 kW) and its charge is that times the demand price the meter had
when the bucket was made. The charge of the window is the highest of them, which
for one price is the peak times the price. The summary gives each such meter a demand with the peak
in kW, when it started, and the charge, and puts the charge into the window’s cost
and the cost of a unit made. The meter’s own cost stays what the energy cost.
Like the energy price, the demand price is kept with each bucket when it is made (migration 0030), so changing a demand price changes what is counted from then on and never the month that is over. Buckets made before the meter had a demand price carry none: they show a peak and no charge.
A utility bills demand over its billing month, so ask for this_month or
last_month to see the line on the bill; a shorter window gives the charge for
the highest quarter hour inside it. If the peak quarter hour was not read the
whole way (peak_covered_seconds below 900), the peak is understated, and the
screen says so. The Today sensors below count energy only: a demand charge is a
line of the month’s bill, not a thing that accrues all day.
The cost of a unit made
Section titled “The cost of a unit made”The cost over a window of the priced meters you choose, divided by what a
production meter counted in the same window. The summary gives one for each
production meter and currency. When nothing was made the cost per unit is
null with the reason nothing_made, and the screen says “Nothing made”: that
is no answer, not zero and not a divide by zero. The same when things were made and
no priced meter has counted any use yet (nothing_counted, “No energy counted
yet”): the meters are read one after another, so a register that has not moved yet
is not a free product. A meter that counted something at a price of nothing still
counts, and gives a cost of nothing.
GET /api/energy/summary?period=today&meters=line2-electricity,line2-air&per=line2-parts
works it out for one line: meters names the meters whose cost goes in, per
the production meter. Without them, it is every priced meter over every
production meter.
Windows
Section titled “Windows”period is today, yesterday, this_week (weeks start on Monday),
last_week, this_month, last_month, last_7_days or last_30_days, a shift,
or give from and to as RFC 3339 (at most 400 days). Days, weeks and months are the
site’s, in its own timezone (HOTLOOP_TIMEZONE): midnight is the
plant’s midnight, and the day of 23 or 25 hours is the real day. A shift is written
shift:06:00-14:00, from and to on a quarter hour in the site’s clock, and a to
that is not after the from runs past midnight (shift:22:00-06:00). shift: is
the latest one to have started, which is the one running now when one is, and
last_shift: is the one before it. A shift is built from the calendar day, so
the night the clocks change is as long as it really was. The screen has a Shift
box beside the periods, and the same names go in the MCP tools’ period. Series are cut
in quarter (at most 8 days), hour, day or month steps.
On the screen
Section titled “On the screen”The Energy screen (Plant group) has a period picker, the cost of the period, the cost per unit made for each production meter, and a card for each meter: what it used, what it cost, a bar for each hour (or day), and, when it applies, whether it is being read, whether part of it is estimated, and how much of the period a power meter was read for. A bar with a dashed outline is estimated. A meter that cannot be read says why. Every word is in all 14 languages.
Entities
Section titled “Entities”Each meter gives sensors that every screen and rule can use:
| Entity | State |
|---|---|
sensor.<meter>_today |
what the meter used since the site’s midnight, in its unit |
sensor.<meter>_cost_today |
what that cost (a priced meter) |
sensor.<production meter>_cost_per_unit_today |
today’s cost over today’s units made. unknown until something is made, and when meters are priced in two currencies |
They are platform energy, they read, and they take no service. A meter that
stopped answering is still what it used so far, with quality uncertain and
meter_status saying why.
Agents read and manage meters through the same routes:
| Tool | Does |
|---|---|
list_energy_meters, get_energy_meter |
the meters, how each is being read, and today’s use and cost |
get_energy_summary |
what each meter used and cost over a named period, the cost in each currency and the cost of a unit made |
get_energy_series |
one meter’s use over a named period in steps |
create_energy_meter, update_energy_meter, delete_energy_meter |
make, change and remove a meter. Each needs a reason and is audited |
The meters and per filters of the cost per unit are REST query parameters.
Backup and updates
Section titled “Backup and updates”Three tables hold it (migration 0029): energy_meters, energy_meter_state and
energy_buckets, all in the backup. Migration 0030 adds the demand price to the
meters and to each bucket. The migrations only add. A bucket is about
100 bytes, so a meter is about 3.5 MB a year.
What it does not do
Section titled “What it does not do”- It does not know your shifts. A shift is named in the request, as
shift:06:00-14:00; there is no list of the plant’s shifts to pick from, and a shift not on a quarter hour is refused because the buckets are quarter hours. - It does not bill demand for you. The charge is the highest quarter hour in the window times the price; a utility’s ratchets, minimum demands and power factor charges are not in it.
- It does not read a meter for you. The tag arrives first: add the device (Modbus, MQTT, OPC UA, or Emberburn for a simulated one), then make the meter.