Skip to content
GitHub

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 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.

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.

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.

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 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.

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.

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.

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.

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.

  • 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.