troubleshooting guide

HSEM Troubleshooting Guide

This guide helps you diagnose and fix common HSEM problems. Work through the symptoms below in order — the first sections cover foundational issues (missing data, wrong data) that must be fixed before later sections (battery behaviour) can be addressed.

---

Quick diagnostic checklist

Before diving into individual symptoms, check these four sensors in the Home Assistant Developer Tools → States tab. They answer 90 % of questions.

Sensor	Look for
sensor.hsem_degraded_mode	Must be ok. error means no hardware writes. degraded means some data is missing but writes still work.
sensor.hsem_hardware_writes	Must be allowed. blocked means the system cannot send commands to the inverter.
sensor.hsem_read_only	Must be off. on means you intentionally disabled writes.
sensor.hsem_applier_status	Must be ok or skipped. failed means the last hardware write did not take effect.

If any of these show a non-ideal value, start with the matching section below.

---

1. Missing data

Symptoms

• sensor.hsem_degraded_mode shows degraded or error
• sensor.hsem_missing_entities shows a number > 0
• sensor.hsem_working_mode shows missing_input_entities
• sensor.hsem_plan_explanation → data_quality_complete is false
• The HSEM device in HA shows unavailable entities

Checks & likely causes

1a. Huawei Solar entities missing after HA restart

The Huawei Solar integration needs one poll cycle before its entities become available. HSEM can read them only after that.

• Check: Look at sensor.hsem_degraded_mode → missing_entities attribute. Are battery/power entities listed?
• Fix: Wait 2–3 minutes after HA restart for the inverter to respond. HSEM automatically shortens its update interval to 1 minute while entities are missing and returns to the configured interval when data is available.

1b. Wrong device IDs in the HSEM config flow

The Huawei Solar step in the config flow requires device IDs for the inverter and batteries. If these IDs don't match your physical devices, no battery or inverter entities will be found.

• Check: HSEM → Configure → Huawei Solar step. Verify the Inverter Device ID and Batteries Device ID match the Device Info shown in the Huawei Solar integration's device list.
• Fix: Correct the device IDs in the config flow and save.

1c. Price feed (Energi Data Service) not installed or broken

HSEM reads electricity prices from the energidataservice integration. If it's missing, not configured, or its entities are unavailable, prices default to 0.0.

• Check: Look at the data_quality attribute on sensor.hsem_plan_explanation. Are today_price_missing_hours or tomorrow_price_missing_hours high?
• Fix: Verify the EDS integration is installed, configured for your price area, and its entities show valid data in HA Developer Tools → States.

1d. Critical sensors missing → Error mode

If any of these five entities are missing, HSEM enters error mode and blocks all hardware writes:

Sensor label keyword	Entity description
batteries_state_of_capacity	Battery state of charge
batteries_maximum_charging_power	Max charging power
batteries_maximum_discharging_power	Max discharging power
batteries_rated_capacity	Battery rated capacity
house_consumption_power	House consumption power

• Check: sensor.hsem_degraded_mode → missing_entities attribute.
• Fix: Correct device IDs or reinstall the Huawei Solar integration.

1e. Consumption energy sensors not ready after restart

The sensor.hsem_house_consumption_energy_* sensors use HA's statistics table. After a restart they need the first statistics period to complete before they can restore.

• Fix: Wait for the next statistics cycle (usually 5 minutes). HSEM shortens its interval to 1 minute until these are ready.

---

2. Wrong prices

Symptoms

• The planner makes decisions that don't match your intuition about electricity prices
• sensor.hsem_plan_explanation → selected_strategy doesn't match price patterns you see in EDS
• Charge/discharge happens at unexpected times

Checks & likely causes

2a. EDS update interval mismatch

The planner uses an eds_share conversion factor that depends on whether EDS publishes data every 15 minutes or every 60 minutes. If the HSEM config says one interval but EDS actually publishes at the other, all prices are silently scaled wrong.

• Check: HSEM → Configure → Energi Data Service step. Verify the EDS Update Interval (15 or 60) matches what your EDS integration actually uses. Check the EDS integration documentation for your price area.
• Fix: Change the interval to match reality.

2b. Grid fee or tax configuration

HSEM adds grid fees and taxes to spot prices. Wrong values here distort the cost function.

• Check: HSEM → Configure → Energi Data Service step. Review Grid Fee (net-tariff), Grid Tariff (transmissions-net), El-afgift, and Reduktion. Verify against your electricity bill.
• Fix: Correct any mismatched values.

2c. Export minimum price blocks all export

The export_min_price setting prevents grid export when the export price is below that threshold. If set too high, HSEM never exports — the battery stays full and the inverter physically blocks export.

• Check: HSEM → Configure → Energi Data Service step. Export Minimum Price. Compare against current export spot prices.
• Fix: Lower or set to 0 if you want to export at all positive prices.

2d. Negative prices trigger force-export

If the live import price is negative, the runtime recommendation resolver forces force_export mode regardless of planner output. This is correct behaviour — the battery should discharge to avoid paying to import.

• Check: sensor.hsem_working_mode shows force_export during a slot with negative prices. This is normal — verify the spot price in EDS.
• Fix: If you don't want force-export, disable it in your battery schedule configuration (set Allow Forced Export to off).

---

3. Wrong PV forecast

Symptoms

• The planner charges or discharges at unexpected times despite plenty of solar
• sensor.hsem_plan_explanation → data_quality shows tomorrow_pv_missing_hours > 0
• sensor.forecast_accuracy shows mae_pv_kwh consistently high
• Battery does not charge from solar when PV is available

Checks & likely causes

3a. Solcast integration not installed or wrong entity

HSEM reads PV forecasts from the solcast_solar integration. If it's missing or the entity ID is wrong, all PV estimates default to 0.0.

• Check: HSEM → Configure → Solcast step. Verify the Solcast Entity ID points to an existing, working entity.
• Fix: Install the solcast_solar integration and configure HSEM to use the correct entity. The entity should show forecast values > 0 during daylight hours.

3b. Solcast forecast attribute key

HSEM reads a specific attribute from the Solcast entity (configurable as Forecast Likelihood). If the attribute key doesn't match what Solcast exposes, PV forecast will be all zeros.

• Check: In HA Developer Tools → States, find your Solcast entity and inspect its attributes. Check which attribute key holds the forecast data (typically pv_estimate, pv_estimate10, or pv_estimate90).
• Fix: Set the Forecast Likelihood field in the HSEM Solcast config step to match the attribute name that exists.

3c. Seasonal mode classification wrong

HSEM classifies each month as winter or summer based on the Winter Months setting. In winter mode the planner uses batteries_wait_mode — it does not actively charge from solar. In summer mode it uses solar charging strategies.

• Check: sensor.hsem_plan_explanation → forecast_mode. Does it match your expectation for the current month?
• Fix: HSEM → Configure → Months step. Adjust the Winter Months list so months are correctly classified for your climate.

3d. Persistent forecast bias (Solcast consistently over/under)

Use the sensor.forecast_accuracy sensor to track forecast quality over time.

• Check: mae_pv_kwh (mean absolute error in kWh) and bias_pv_kwh (systematic over/under prediction).
• Fix: If bias is consistently high in one direction, consider switching the Forecast Likelihood to a different percentile (e.g. from pv_estimate to pv_estimate90 for a conservative estimate, or to pv_estimate10 for an optimistic one).

---

4. Inverter write failures

Symptoms

• sensor.hsem_applier_status shows failed
• sensor.hsem_degraded_mode shows error (writes blocked)
• sensor.hsem_hardware_writes shows blocked
• Battery does not change behaviour despite planner recommendations
• sensor.hsem_plan_explanation → last_apply_status is failed

Checks & likely causes

4a. Degraded mode = Error

When critical entities are missing, all hardware writes are blocked. See Section 1d.

• Fix: Resolve the missing critical entities first.

4b. Read-only mode active

switch.hsem_read_only being on blocks all writes intentionally. This is a safety feature for when you want to monitor the planner without letting it control hardware.

• Check: sensor.hsem_read_only state. Is it on?
• Fix: Set switch.hsem_read_only to off.

4c. Write accepted but unverified (transient)

unverified status means the write was sent but the read-back timed out or returned None. The inverter may still have accepted the value.

• Check: sensor.hsem_applier_status → last_apply_details attribute. Look for entries with status unverified.
• Fix: Usually self-corrects on the next cycle (HSEM retries up to 3 times per write). If persistent, the inverter entity may be slow to update — check Huawei Solar integration health.

4d. Persistent write failures

failed status means all 3 retry attempts were exhausted — the inverter did not accept the value.

• Check: sensor.hsem_applier_status → failed_entities attribute for the specific entity IDs that failed.
• Check: Home Assistant logs for errors from the huawei_solar integration.
• Fix:
  1. Verify the inverter is online and reachable.
  2. Check that the working mode or settings being written are valid for your inverter model.
  3. Restart the Huawei Solar integration.
  4. If the failure is on set_tou_periods, check your battery schedule configuration for invalid values.

4e. Force working mode override active

When select.hsem_force_working_mode is set to anything other than auto, the planner is bypassed and HSEM writes the forced mode directly. If that mode is invalid for your inverter, writes may fail.

• Check: select.hsem_force_working_mode state.
• Fix: Set to auto to restore normal planner control, or set a valid mode for your inverter.

---

5. Plan not changing

Symptoms

• sensor.hsem_plan_explanation → selected_strategy stays the same for many hours
• The working mode sensor never changes recommendation
• You expect the battery to switch between charge/discharge but it doesn't

Checks & likely causes

5a. Hysteresis holding previous plan

The planner has hysteresis: it keeps the previous plan if the new plan's improvement is less than 5 %. This prevents oscillation between similar strategies.

• Check: sensor.hsem_plan_explanation → hysteresis_active (is it true?) and hysteresis_reason.
• Fix: This is normal behaviour. If you want more responsive switching, reduce the hysteresis threshold in HSEM → Configure → Batteries Hysteresis step.

5b. Window hysteresis preventing slot-level changes

planner_window_hysteresis_minutes prevents charge↔discharge toggles near schedule boundaries. When enabled, a slot's recommendation is locked once a window starts.

• Check: HSEM → Configure → Batteries Hysteresis step. Window Hysteresis value (0 = disabled).
• Fix: Set to 0 to disable window hysteresis, or lower it if slots are staying locked too long.

5c. Only one schedule active

If you only have one battery schedule configured and it covers only part of the day, the battery will be in batteries_wait_mode outside that window.

• Check: HSEM → Configure → Batteries Schedule steps (1, 2, 3). Are schedules enabled? Do they cover the hours you expect?
• Fix: Enable additional schedules or widen the hours. Each schedule defines when a specific working mode is permitted.

5d. Planner in winter wait mode

In winter months, the planner uses batteries_wait_mode by default — it doesn't actively charge or discharge. This is intentional.

• Check: sensor.hsem_plan_explanation → forecast_mode is winter and selected_strategy is winter_wait.
• Fix: If this is unexpected, check the Winter Months setting in the Months config step. Adjust if your climate has different seasonal patterns.

5e. Consumption weights prevent plan selection

If the consumption prediction weights don't sum to 100 %, the planner logs a warning and may produce suboptimal plans.

• Check: HSEM → Configure → Weighted Values step. Do the weights sum to 100 %?
• Check: hsem.log for the warning "Consumption weights sum to X, not 100."
• Fix: Adjust weights to sum to exactly 100 %.

---

6. Battery not charging

Symptoms

• Battery SoC stays low or doesn't increase
• sensor.hsem_working_mode never shows batteries_charge recommendations
• Battery draws no power from grid or solar despite low SoC

Checks & likely causes

6a. No charge schedule configured or active

HSEM only commands charging when a schedule permits it and the planner assigns charge recommendations to slots.

• Check: sensor.hsem_plan_explanation → selected_strategy. Does it include "charge"? Look at the planned_slots attribute — are any marked with a charge recommendation?
• Fix: Enable a battery schedule in the config flow and ensure it covers the hours when you want charging to happen.

6b. SoC already at or above charge cutoff

HSEM respects the configured charge cutoff. If the battery is already above the cutoff, the planner won't schedule charging.

• Check: HSEM → Configure → Huawei Solar step. Grid Charge Cutoff SoC value.
• Check: Current battery SoC vs the cutoff value.
• Fix: Adjust the cutoff value if desired. Note: this is a safety setting — setting it too high may reduce battery lifespan.

6c. Winter season blocks solar charging

In winter mode, the planner does not actively charge from solar. It waits for prices to drop below the charge threshold.

• Check: sensor.hsem_plan_explanation → forecast_mode is winter.
• Fix: If you want solar charging in what HSEM considers winter, adjust the Winter Months in the Months config step.

6d. Charge efficiency configured incorrectly

If charge_efficiency is set to 100 % but the actual round-trip efficiency is lower, the planner overestimates how much energy reaches the battery.

• Check: HSEM → Configure → Battery Economics step. Charge Efficiency value.
• Fix: Set to realistic values (e.g. 95–98 % for lithium-ion).

6e. Cycle cost too high

If the purchase_price is set very high and battery_cycle_cost is auto-derived from it, the cycle cost can be high enough that the planner decides charging is not economical.

• Check: HSEM → Configure → Battery Economics step. Purchase Price and Cycle Cost values.
• Fix: Set purchase_price to your actual battery purchase price per kWh of usable capacity for accurate cycle cost calculation.

6f. Consumption exceeds available energy

If house consumption is higher than available solar + low-price grid energy, the planner may determine there's no surplus to charge the battery.

• Check: sensor.hsem_net_consumption — is it positive (house draws from battery/grid) during sunny hours?
• Fix: This is normal if consumption is high. The planner correctly prioritises serving house load over charging.

6g. Non-critical configuration issues

• batteries_charging_cutoff_capacity in the Huawei Solar step: sets the SoC at which the battery physically stops charging. Must coordinate with the planner's charge targets.
• end_of_discharge_soc: HSEM uses this for safety floors but incorrect values can confuse the planner.

---

7. Battery not discharging

Symptoms

• Battery SoC stays high or doesn't decrease during peak price hours
• sensor.hsem_working_mode never shows batteries_discharge recommendations
• Battery does not export or serve house load when expected

Checks & likely causes

7a. No discharge schedule configured or active

Discharge requires a battery schedule with a discharge-compatible mode enabled.

• Check: sensor.hsem_plan_explanation → selected_strategy. Does it include "discharge"?
• Fix: Enable a battery schedule that permits discharge during the hours when you want to discharge.

7b. SoC at or below end-of-discharge floor

HSEM respects the battery's minimum SoC. If the battery is already near the end-of-discharge threshold, no discharge is scheduled.

• Check: Current battery SoC vs the configured end_of_discharge_soc in the Huawei Solar config step.
• Fix: Lower the end_of_discharge_soc if safe for your battery chemistry. Never set below the manufacturer's recommended minimum.

7c. Export minimum price blocks all export

See Section 2c. If export_min_price is set above current export prices, the inverter blocks grid export. The battery may still discharge to serve house load, but won't export.

• Check: Current export spot price vs the export_min_price setting.
• Fix: Lower the threshold if you want to export during low-price periods.

7d. Discharge efficiency configured incorrectly

If discharge_efficiency is unrealistically high, the planner overestimates usable energy from the battery.

• Check: HSEM → Configure → Battery Economics step. Discharge Efficiency value.
• Fix: Set to realistic values (e.g. 95–98 %).

7e. Capacity loss factor too high

capacity_loss_pct (default 30 %) accounts for battery wear. Higher values make cycling more expensive in the cost function, which may reduce discharge.

• Check: HSEM → Configure → Battery Economics step. Capacity Loss %.
• Fix: Adjust to match your battery's expected lifetime degradation.

7f. Excess export feature misconfigured

The Excess Export feature (in the Batteries Excess Export config step) discharges battery surplus above a buffer to the grid. If disabled or the buffer is too high, excess energy stays in the battery.

• Check: Is the feature enabled? What is the discharge_buffer value?
• Fix: Enable the feature and set a reasonable buffer for your needs.

7g. Export physically blocked at inverter level

HSEM writes set_maximum_feed_grid_power_percent to 0 % when export is not allowed for the current slot. If the inverter's own export limit is also set to 0, the battery cannot export regardless of HSEM's decision.

• Check: The inverter's grid export settings in the Huawei Solar integration or FusionSolar app. Ensure export is permitted at the inverter level.

---

When to check the logs

HSEM log (hsem.log)

Located in your Home Assistant config directory. Enable verbose logging by turning on switch.hsem_verbose_logging before collecting logs.

Search for these patterns in hsem.log:

Pattern	Meaning
[core] run_planner ABORTED — no slots generated	interval_minutes or interval_length_hours config error
Consumption weights sum to	Weight misconfiguration
MILP: SoC penalty violations	Battery was overcharged at planning start
Hardware writes BLOCKED	Error mode or read-only active
[selector] No eligible candidates	All plans rejected during validation
[selector] HYSTERESIS kept previous plan	Plan switch suppressed by hysteresis
Sensor read failed for entity_id	Specific entity reading error — check entity
EV is physically charging but no slot has load > 0	EV charging without planned load

Home Assistant log (home-assistant.log)

HSEM messages do not propagate to home-assistant.log by default. To see them there, add to configuration.yaml:

logger:
  logs:
    custom_components.hsem: debug

Huawei Solar integration logs

Check the Huawei Solar integration for network errors, timeouts, or authentication failures. These affect HSEM's ability to read and write hardware entities.

---

System recovery steps

If you've checked everything and HSEM still doesn't work:

1. Reload the integration: HA Settings → Devices & Services → HSEM → ⋮ menu → Reload.

2. Restart HA: Full restart clears any stuck state.

3. Re-run config flow: HSEM → Configure → step through all config steps → save. This re-validates all entity IDs and device IDs.

4. Enable extended attributes: Turn on switch.hsem_extended_attributes to expose additional diagnostic attributes on the working mode and plan explanation sensors.

5. Enable verbose logging: Turn on switch.hsem_verbose_logging, wait for 2–3 coordinator cycles, then collect hsem.log from the HA config directory. The log shows every planning step in detail.

6. Check for known issues: Review open issues at github.com/woopstar/hsem/issues.

---

Key diagnostic entities reference

Entity	Type	Purpose
sensor.hsem_degraded_mode	Sensor	ok / degraded / error
sensor.hsem_missing_entities	Sensor	Count of missing input entities
sensor.hsem_hardware_writes	Sensor	allowed / blocked
sensor.hsem_read_only	Sensor	on / off
sensor.hsem_applier_status	Sensor	ok / unverified / failed / skipped / pending
sensor.hsem_plan_explanation	Sensor	Active strategy + detailed attributes
sensor.hsem_working_mode	Sensor	Current slot recommendation
sensor.forecast_accuracy	Sensor	PV/load forecast accuracy metrics
switch.hsem_read_only	Switch	Toggle read-only mode
switch.hsem_verbose_logging	Switch	Toggle verbose HSEM logging
switch.hsem_extended_attributes	Switch	Expose additional sensor attributes
select.hsem_force_working_mode	Select	Manual working mode override