Repository navigation
Plugin energy meter
Monitors Shelly three-phase electricity meters and stores import, export, tariff, cost and solar calculations.
| Item | Value |
|---|---|
| Version | 1.0.7 |
| Category | Energy and building control |
| Author | Martin Pihrt |
| License | GPL-3.0 |
| OSPy |
3.0.318 or newer |
| Python |
3.8 or newer |
| Permissions |
files, network
|
| Hardware | No dedicated hardware requirement declared |
| Dependencies | Shelly Cloud Integration (optional), Database Connector (optional) |
| Python/OS packages |
requests (required) |
| Interfaces | Mobile API v1 |
| Source | Open the plug-in directory |
Monitors Shelly three-phase electricity meters and stores import, export, tariff, cost and solar calculations.
Energy Meter is a multi-meter electricity monitor for OSPy. It is designed for Shelly Pro 3EM and Shelly 3EM-63T Gen3 devices and keeps import, export, per-phase power, prices and solar-system calculations in a persistent history.
Direct LAN / IP is the default and recommended source. Enter an IP address, an optional port, or a DNS name such as meter.local; OSPy reads http://HOST/rpc/Shelly.GetStatus directly, works without Shelly Cloud or Internet access, and can use Shelly local digest authentication. The second source is the device cache of Shelly Cloud Integration. That mode requires Shelly Cloud Integration to be installed, configured, enabled and running. Energy Meter distinguishes a missing or disabled Shelly ID from an enabled device that is still waiting for its first cached reading after startup or configuration changes, including when paired with the previous parallel-list Integrator interface. A waiting meter is retried every five seconds without an error traceback, while successfully read meters retain the configured sampling interval and Diagnostics reports a waiting state until data arrives.
Any number of meters can be configured. Assign each meter one of these roles: Grid connection for import from and export to the public grid, Solar production for photovoltaic generation, Load / consumption for a separately measured consumer, or Auxiliary for an independent value. Direction can be inverted for a physically reversed current-transformer installation. Grid export is never labelled as solar production.
Each meter also has an accounting mode. Phase-by-phase preserves the original behavior and adds import and returned energy from L1, L2 and L3 independently. Net / vector sum compensates phase import and export inside every completed sampling interval and records only the remaining direction as the accounted total. For example, 6.230 kWh raw phase import and 6.049 kWh raw phase export in the same interval produces 0.181 kWh accounted import and no accounted export. This mode is intended for grid connections whose utility meter settles the vector sum of all phases. It does not net the complete day: import in one interval and export in another remain separate. Existing configurations default to Phase-by-phase.
When both Grid and Solar production meters are present, the dashboard calculates house consumption as production + grid import - grid export, self-consumption as production - grid export, the self-consumption ratio and energy independence. With only a Grid meter the production value stays unavailable rather than being guessed. Battery charging and discharging are not inferred without a dedicated measurement path.
Shelly cumulative active and returned energy counters are persisted after every successful sample in an atomically replaced JSON state file. OSPy therefore resumes from the previous baseline after restart. A lower counter is treated as a reset or meter replacement: the plug-in establishes a new baseline and does not create an artificial consumption spike. The overview also provides a CSRF-protected Reset baseline / replace meter action for planned replacement or factory reset. Local interval history is appended to history.jsonl, avoiding a rewrite of the complete history on every sample. Existing history.json data is read automatically for backward compatibility. Every new interval stores the applied accounting mode; older records without that field retain Phase-by-phase meaning. Changing the mode affects only future intervals and does not rewrite retained history.
Intervals spanning an OSPy restart are retained as one interval and period aggregation apportions their energy by overlap with the requested day, month or year. This prevents loss of cumulative energy and avoids assigning an entire restart interval to the wrong calendar period. Calendar days use the local date and time configured on the OSPy server, start at 00:00 inclusive and end at the next 00:00 exclusive. The Shelly cumulative counters are not reset at midnight.
The overview and history show raw L1, L2 and L3 import/export values and the accounted total selected by the stored mode, plus live power, a selectable retained calendar day, yesterday, the current month and the current year. In Net / vector sum mode the accounted total intentionally need not equal the sum of the three raw directional phase columns. Every overview period displays its historically calculated cost and feed-in income from the accounted totals. Separate responsive energy and power graphs offer 7-, 30- and 365-day views: energy includes raw grid import and export L1/L2/L3, accounted import/export totals and solar production, while power includes L1/L2/L3/total for every configured meter. History can be downloaded as CSV, including the accounting mode, or permanently deleted by an administrator. Overview totals and selected-day results are calculated from that interval history, so deleting it also clears those values and they cannot be reconstructed from the retained baseline. The cumulative-counter baseline remains only to let the next sample continue without a false energy spike. Local JSON history is supported without another plug-in; SQL history and dual local-plus-SQL logging require Database Connector. Record retention is configurable and zero means unlimited. Shorter sampling intervals follow rapid changes between import and export more closely but create more history records. Boolean settings use the standard OSPy switches, while each tariff uses localized Monday-through-Sunday buttons to select its active days.
Set a currency, default import price and default feed-in price. Optional tariffs match weekdays and time ranges, including ranges crossing midnight, and equal start and end times define a full-day tariff. The first matching tariff is used. The tariff identifier, tariff name, currency, actual import and feed-in prices, cost and income are written to local JSON and SQL history and CSV export. Intervals crossing a tariff boundary use time-weighted prices for their applicable segments without creating artificial energy or power samples. Changing prices or currency later does not recalculate or relabel historical records. The history table displays the stored currency and both unit prices so the calculated totals can be audited. Overview monetary totals include only records using the currently configured currency because the plug-in does not perform currency conversion, while energy totals continue to include every applicable record.
The mobile API v1 card contains today’s grid import and export, solar production and house consumption when those values are actually measurable, current power for every configured meter and bounded history. Show on Home adds a compact current-day import/export summary to the OSPy Home plug-in section.
Local files are stored in the OSPy plug-in data directory as state.json, the backward-compatible history.json, and the append-only interval journal history.jsonl. Authenticated administrators can read /plugins/energy_meter/status_json for current meters and period summaries, /plugins/energy_meter/graph_json?from=UNIX&to=UNIX for bounded history and /plugins/energy_meter/log_csv for CSV export. Standard OSPy mobile plug-in discovery exposes mobile_status() and mobile_cards().
The OSPy diagnostics page calls health(). It reports worker state, whether at least one configured meter is online, the last successful read, the latest error and per-meter source/status details. Connection errors are also written to the OSPy event log.
The following notes are generated from the help page shipped with this plug-in. Field names are also explained directly in the OSPy settings page.
Use Direct LAN / IP whenever possible. Enter an IPv4 or IPv6 address, optional port, or a DNS name resolvable by the OSPy computer. The plug-in reads Shelly.GetStatus locally and does not require Internet access. Shelly local authentication uses the configured user and password.
Shelly Cloud Integration is an alternative source. It only works when that plug-in is installed, enabled, configured and already exposes the selected three-phase meter.
After OSPy or Shelly Cloud Integration starts, Energy Meter recognizes a configured meter that is still waiting for its first cached reading. Only that meter is retried every five seconds without recording a failure traceback or changing the configured sampling interval for other meters.
Grid connection records energy imported from and exported to the public grid. Solar production records generated energy. Load records a separate consumer and Auxiliary is an independent meter. Grid export is never presented as solar production. With both Grid and Solar meters, house consumption equals production plus grid import minus grid export; self-consumption equals production minus grid export. Battery charging and discharging are not inferred without a dedicated meter.
Phase-by-phase accounting adds import and export from every phase separately. Net / vector sum accounting compensates simultaneous phase import and export inside every sampling interval, then records only the remaining import or export as the accounted total. This matches grid meters that settle the vector sum of all phases. It is not a net calculation over the complete day: import and export in different intervals remain separate. Per-phase history always retains the raw Shelly counter differences for diagnostics. Shorter sampling intervals follow rapid direction changes more closely, while producing more history records.
Current Shelly cumulative counters and the previous sample are persisted atomically. OSPy therefore continues after restart without losing the counter baseline. If a counter decreases, the plug-in records a reset and establishes a new baseline without adding a false energy spike. Use Reset baseline before replacing or resetting a meter.
Each completed sampling interval stores raw import and export energy plus power for L1, L2 and L3, the configured accounting mode and the accounted totals. The default interval is 60 seconds. Changing the accounting mode affects only new intervals and does not reinterpret retained history. Local history is appended to a journal so the complete history file is not rewritten every minute.
Overview totals and selected-day results are calculated from the retained interval history. Delete history therefore clears these overview values as well. Only the current cumulative-counter baselines are preserved, solely so the next sample continues from the current meter values without adding a false energy spike. Deleted historical totals cannot be reconstructed from the preserved baselines.
Use the calendar-day selector on the overview to inspect any retained past day. Today, yesterday and every selected day follow the local date and time configured on the OSPy server: a day starts at 00:00 inclusive and ends at the next 00:00 exclusive. The physical Shelly cumulative counters are not reset at midnight; the plug-in splits and sums recorded intervals at calendar boundaries.
Applied import and feed-in prices, currency, cost and income are stored permanently with each interval in local and SQL history and CSV export. Equal tariff start and end times mean the complete selected day. If an interval crosses a tariff boundary, its price is calculated as a time-weighted combination of the applicable tariff segments. The history table shows the stored tariff, currency and both applied prices, while the overview displays the resulting cost and feed-in income for the selected day, yesterday, the current month and the current year. Later tariff changes do not recalculate historical prices or totals. Overview monetary totals include only records in the currently configured currency because currencies are not converted or added together.
History can be kept in local JSON, SQL through Database Connector, or both. The OSPy mobile API receives live meter power, period totals and bounded history.
Check OSPy → Diagnostics first and remove passwords, tokens, private addresses and other secrets before sharing logs. Report reproducible plug-in problems in the OSPy-plugins issue tracker.
Start
Reference
Catalog sections