All guides

Reference · 6 min

Power sign conventions: charge, discharge, import and export

The most common battery or inverter integration mistake is a flipped power sign. Plus means charging for one vendor and discharging for another. Wesfin uses one canonical convention, and vendor signs are converted at the adapter boundary.

The Wesfin canonical convention

The sign describes the direction of energy from the point of view of the device or the grid connection point. The convention is the same in the Lab, in device profiles and in the telemetry contract.

FieldPlus (> 0) means
asset_active_power_kwThe device supplies energy: the battery discharges. Minus means the device consumes: the battery charges, the heater heats.
grid_active_power_kwThe site imports energy from the grid. Minus means export to the grid.
target_active_power_kwA command to discharge. Minus is a command to charge.
canonical telemetry
{
  "asset_active_power_kw": -4.2,   // the battery charges at 4.2 kW
  "grid_active_power_kw": 1.3,     // the site imports 1.3 kW from the grid
  "soc_pct": 73.5
}

Remember one rule: the device sign is “gives or takes”, the grid sign is “buy or sell”. They are independent: a battery can charge (minus) while the site exports (also minus) if solar produces more.

Loads: water heater, heater, charger

A controllable load only consumes, so its canonical power is negative. Curtailing consumption means moving the value towards zero.

An example from the Lab test vectors: baseline consumption -5 kW, a bounded command to -3 kW for 10 seconds, then a measured return to -5 kW. A positive target for a load is rejected, as is a target outside the declared floor and cap.

Common traps

What the vendor reportsWhat to do
Plus while the battery chargesInvert the sign in the adapter: asset_active_power_kw = -vendor_power.
Power in wattsDivide by 1000. In the Home Assistant mapping this is unit W on active_power.
A scaled integer: 735 means 73.5%Divide (735 / 10.0) rather than multiply by 0.1 so the value is exact.
Separate charge and discharge registers, both positiveCombine into one field: discharge minus charge.
A grid meter with “export = plus”Invert for grid_active_power_kw: import must be plus.
adapter conversion
// Vendor: power_w = +4200 while charging, battery_soc = 735 (tenths of a percent)
asset_active_power_kw = -(power_w / 1000.0)   // -4.2
soc_pct               = battery_soc / 10.0    // 73.5

How the Lab catches a flipped sign

  1. The profile fixes the convention

    In the profile every telemetry field has a canonical name and unit. In the Home Assistant mapping the read sign is the field's sign (for example active_power.sign: 1 or -1), and the sign of the setpoint the Lab writes is set separately by write_sign.

  2. A command has a known direction

    A bounded discharge command of +0.5 kW must produce a measured +0.5 kW. If the measurement shows -0.5 kW, the sign is flipped.

  3. The measurement is independent

    MEASURED in the evidence refers to a canonical observation, not the device's acknowledgement. So a sign error cannot hide behind “command executed”.

A WebAssembly telemetry normalisation module performs the same conversion in code, and the Lab checks each of its results independently.