Cumulative vs gauge — choosing the right data value type

Every meter has a "data value type" that tells the platform how to interpret incoming values. Getting this wrong produces silently incorrect totals — there is no error, just wrong numbers on the dashboard.

Cumulative — the meter is an odometer. Each reading is the all-time total since installation (e.g. 12345.6 kWh, then 12353.6, then 12361.6). Consumption for a period is computed as last_value − first_value, with automatic handling of meter resets and rollovers.

Use cumulative when:

• Your gateway reads a cumulative register on the meter (e.g. Carlo Gavazzi EM24 register 52, most Modbus and M-Bus utility meters)
• The displayed value on the meter face matches what's being pushed
• You want the most robust billing-grade behaviour — missing one push doesn't lose consumption, because the next reading captures everything since the last

Gauge — each reading is a per-period delta already (e.g. "8 kWh used between 14:00 and 15:00"). Consumption for a longer period is SUM(values).

Use gauge when:

• The source genuinely only emits per-interval deltas (some BMS APIs)
• The source emits instantaneous values like power (kW), temperature (°C), or flow rate that cannot be cumulated

Why cumulative is preferred for billing

• Robust to missed deliveries: a missed hour means nothing is lost. The next push contains the consumption since the last successful reading.
• Meter face matches dashboard: an auditor can read the kWh on the meter and reconcile against the platform.
• Tamper detection: an odometer cannot go backwards undetected. Anomaly detection runs against rate-of-change.

Where to set this: Buildings → your building → Meters tab → click meter → Data Value Type. If the field is blank, the platform defaults to cumulative.

If you've been pushing the wrong type: historical totals will recalculate on the next dashboard load once you fix the field — no data needs to be re-imported.