Energy Data Foundation

1. Start with evidence, not a brand list

A device is useful to an automation only when Home Assistant exposes the right entity with the right meaning. Two meters from the same brand may differ by model, region, firmware, integration, or account. This guide therefore checks entity behaviour rather than promising compatibility from a logo.

2. Separate power, energy, demand, and price

Home Assistant stores entity states as text, so “numeric” means the current state can be parsed as a finite number. Values such as unknown, unavailable, empty text, or a price containing a currency symbol are not numeric states. The unit belongs in the unit_of_measurement attribute, not inside the state.

3. Build an entity inventory in Developer Tools

1. Open Developer Tools → States. Search by the integration or device name. Do not choose an entity from its friendly name alone.
2. Copy the exact entity ID. Record the current state, unit_of_measurement, device_class, and what physical quantity the integration documentation says it represents.
3. Check numeric form. In Developer Tools → Template, replace the example ID below and confirm the last line returns True.
4. Observe real behaviour. Use an appliance through its normal controls and watch at least two update cycles. Never create a test by bypassing device or electrical protection.
5. Write down uncertainty. “Probably import” is not evidence. Keep the entity out of automation until its meaning and direction are confirmed.

{{ states('sensor.your_candidate') }}
{{ state_attr('sensor.your_candidate', 'unit_of_measurement') }}
{{ state_attr('sensor.your_candidate', 'device_class') }}
{{ is_number(states('sensor.your_candidate')) }}

The States tool shows current software state; it does not prove a meter, clamp, cable, or circuit is physically correct.

4. Prove signed grid semantics

The optional Foundation normalizer expects one signed net-grid power entity: positive means import from the grid and negative means export to the grid. A house-consumption sensor, PV-production sensor, or inverter-output sensor is not the same quantity.

If your integration exposes separate import and export power entities, neither one by itself satisfies the signed-source contract. Combining them can be valid only when their units, update timing, and semantics are understood. The supplied file does not silently make that assumption.

5. Check freshness and honest failure

A numeric value can be stale. Watch History or the entity details while normal load changes occur. Record how quickly the source reacts and whether its integration reports regularly when the value stays unchanged. Compare that behaviour with the paid kit's required interval.

• The value changes within the integration's documented or observed cadence.
• A brief source interruption becomes unavailable or otherwise visibly unhealthy instead of silently becoming zero.
• After recovery, the value and unit return without creating a second entity.
• A restart does not change the sign convention or reset cumulative imported energy.
• You know whether identical repeated values count as fresh reports for this integration.

6. Install the optional normalization package

Download the public swf_grid.yaml core plus swf025_energy_data_health.yaml only after identifying one signed grid-power source in W or kW and one cumulative imported-energy source in kWh. Back up Home Assistant first. Install exactly one grid core; if the shared entities already exist, keep that copy and add only the Foundation energy-health file.

1. Replace the single sensor.REPLACE_GRID_POWER in swf_grid.yaml with the verified signed power entity.
2. Replace every sensor.REPLACE_GRID_IMPORT_KWH with the verified cumulative import entity.
3. Run Developer Tools → YAML → Check configuration. Resolve every error before restarting.
4. After restart, confirm these exact entities exist:

sensor.swf_grid_power_w
sensor.swf_grid_import_w
sensor.swf_grid_export_w
binary_sensor.swf_grid_data_problem
sensor.swf025_grid_import_energy
binary_sensor.swf025_energy_data_problem

The swf025_* product namespace is deliberate. It keeps SWF-025's unique IDs and entity IDs separate from SWF-020 and other products. Do not rename them back to bare swf_grid_* IDs. If Home Assistant creates _2, find the stale or duplicate entry under Settings → Devices & services → Entities and resolve it before proceeding; the package's internal references expect the exact IDs above.

7. Dry-run without touching live hardware

If you want to test the package first, create two Number helpers through Settings → Devices & services → Helpers. Give one a range that includes negative values and unit W; give the other a non-negative range and unit kWh. Assign clear IDs such as input_number.swf025_test_grid_power_w and input_number.swf025_test_import_kwh, map those two helpers in a test copy of the package, check configuration, and restart.

Developer Tools → States changes Home Assistant's temporary state representation; it does not command the real device. Use only the test helpers for failure simulation, then change the helper normally to restore it. After the dry run, remap a clean package copy to verified live entities and repeat the configuration check.

8. Per-product readiness matrix

9. Record a go/no-go decision

Save a short record with the date, Home Assistant version, integration name, exact entity IDs, units, sign convention, observed update interval, failure behaviour, and the product row you passed. Repeat the gate after an integration, firmware, meter, tariff, or major Home Assistant change.