battery-charging-optimizer/DIAGNOSIS_SUMMARY.md

# Battery Optimizer PyScript - Diagnosis Summary

**Report Date**: 2025-11-20
**Issue**: Battery optimizer PyScript updated but not working
**Files**: battery_charging_optimizer.py v3.2.0, hastrom_flex_extended.py v2.0

---

## Executive Summary

✅ **Python syntax validation**: Both files compile without errors
✅ **Code structure**: Proper PyScript decorators and patterns used
⚠️ **Potential issues identified**: 4 warnings, 0 critical errors
❓ **Root cause**: Cannot determine without live Home Assistant logs

---

## What Was Checked

### 1. Python Syntax Validation
- Both files successfully compiled with Python 3
- No syntax errors detected
- All imports are standard library (except PyScript-specific)

### 2. PyScript Structure Analysis
**battery_charging_optimizer.py**:
- ✅ 2 services registered: `calculate_charging_schedule`, `execute_charging_schedule`
- ✅ 3 time triggers: 14:05 daily, hourly at :05, midnight at :05
- ✅ 6 try-catch blocks for error handling
- ✅ Proper state access patterns
- ✅ Timezone-aware datetime handling with `zoneinfo`

**hastrom_flex_extended.py**:
- ✅ 1 service registered: `getprices_extended`
- ✅ 3 time triggers: hourly, 14:05 daily, midnight
- ✅ Correct task.executor usage for HTTP requests
- ✅ Creates two sensor entities: `sensor.hastrom_flex_ext` and `sensor.hastrom_flex_pro_ext`

### 3. Code Quality Checks
- Proper error logging with traceback
- Sensible defaults for configuration values
- Defensive programming with null checks (mostly)
- Clear logging messages for debugging

---

## Identified Warnings

### Warning 1: State.getattr() Without Null Check (Line 664)
**Location**: `battery_charging_optimizer.py:664`
```python
schedule_attr = state.getattr('pyscript.battery_charging_schedule')
if schedule_attr and schedule_attr.get('has_tomorrow_data', False):
```

**Risk**: Low - Has subsequent null check, but could be more defensive

**Impact**: Might cause error if state doesn't exist at midnight

---

### Warning 2: Large Schedule in State Attributes
**Location**: `battery_charging_optimizer.py:484-500`

**Risk**: Medium - Schedule with 48+ hours could exceed state size limits

**Impact**: State.set() might fail silently or raise ValueError

**Recommendation**: Monitor state size, consider splitting into separate entities

---

### Warning 3: Service-to-Service Calls
**Locations**:
- Line 650: `pyscript.calculate_charging_schedule()`
- Line 656: `pyscript.execute_charging_schedule()`
- Line 154, 160, 166: `pyscript.getprices_extended()`

**Risk**: Medium - Syntax might differ from expected

**Impact**: Services might not trigger as intended

**Recommendation**: Verify PyScript supports this calling pattern, or use direct function calls

---

### Warning 4: Timezone Module (zoneinfo)
**Location**: Both files import `from zoneinfo import ZoneInfo`

**Risk**: Medium - Requires Python 3.9+

**Impact**: If HA runs Python 3.8 or older, scripts won't load

**Recommendation**: Add fallback to pytz if needed

---

## Most Likely Root Causes (Ranked)

### 1. Missing Required Entities (Probability: HIGH)
**Problem**: Helper entities don't exist in Home Assistant

**Required Entities**:
- `input_boolean.battery_optimizer_enabled`
- `input_boolean.goodwe_manual_control`
- `input_boolean.battery_optimizer_manual_override`
- `input_number.battery_capacity_kwh`
- `input_number.battery_optimizer_min_soc`
- `input_number.battery_optimizer_max_soc`
- `input_number.battery_optimizer_max_charge_power`
- `input_number.charge_power_battery`
- `input_text.battery_optimizer_status`
- `sensor.esssoc`
- `sensor.energy_production_today`
- `sensor.energy_production_today_2`

**How to Check**:
- Developer Tools → States
- Search for each entity

**How to Fix**:
- Create missing helpers via Settings → Devices & Services → Helpers
- Or add to configuration.yaml (see TROUBLESHOOTING_GUIDE.md)

---

### 2. PyScript Not Loading Files (Probability: HIGH)
**Problem**: Files not in correct location or PyScript not enabled

**Correct Location**: `/config/pyscript/` (not `/config/pyscripts/`)

**How to Check**:
1. Settings → Devices & Services → PyScript (should say "Configured")
2. Developer Tools → Services → Search "pyscript" (should show 4+ services)

**How to Fix**:
1. Move files to `/config/pyscript/`
2. Ensure PyScript integration is installed and enabled
3. Call `pyscript.reload` service

---

### 3. Zoneinfo Import Failure (Probability: MEDIUM)
**Problem**: Home Assistant running Python < 3.9

**How to Check**:
```bash
docker exec homeassistant python --version
```

**Expected**: Python 3.9 or higher

**How to Fix**:
- Update Home Assistant to 2021.7+, OR
- Add pytz fallback (see TROUBLESHOOTING_GUIDE.md)

---

### 4. API Call Failures (Probability: MEDIUM)
**Problem**: haStrom API not responding or credentials issue

**Affected**: hastrom_flex_extended.py line 37

**How to Check**: Look in logs for:
```
Fehler beim Abrufen der Strompreise: ...
```

**How to Fix**:
- Verify network connectivity
- Check if API endpoint is accessible: `http://eex.stwhas.de/api/spotprices/flexpro`
- Ensure date format is correct (YYYYMMDD)

---

### 5. Time Trigger Syntax Issues (Probability: LOW)
**Problem**: PyScript doesn't support cron() syntax used

**How to Check**: Look for registered triggers in logs after reload

**How to Fix**:
- Create automations in configuration.yaml as alternative (see TROUBLESHOOTING_GUIDE.md)

---

### 6. State Size Limit Exceeded (Probability: LOW)
**Problem**: Schedule too large for state attributes

**How to Check**: Look for ValueError in logs

**How to Fix**:
- Store only charging hours, not full schedule
- Split schedule into separate entities

---

## Recommended Troubleshooting Steps

### STEP 1: Access Home Assistant Logs

**Method A - Web UI**:
1. Settings → System → Logs
2. Filter for "pyscript"
3. Look for red error messages

**Method B - Download Logs**:
1. Settings → System → Advanced
2. Click "Download Logs"
3. Search file for "pyscript", "battery", "hastrom"

**Method C - SSH Access**:
```bash
tail -f /config/home-assistant.log | grep -i pyscript
```

---

### STEP 2: Reload PyScript and Watch Logs

1. Keep log viewer open
2. Call service: `pyscript.reload`
3. Immediately check for errors

**Look for**:
- `ModuleNotFoundError`
- `NameError`
- `AttributeError`
- `SyntaxError`
- `ValueError`

---

### STEP 3: Verify Services Registered

Developer Tools → Services → Search "pyscript"

**Expected**:
- pyscript.calculate_charging_schedule
- pyscript.execute_charging_schedule
- pyscript.getprices_extended
- pyscript.reload

**If missing**: Scripts didn't load - check logs for why

---

### STEP 4: Test Each Component Manually

**Test 1 - Price Fetcher**:
```yaml
service: pyscript.getprices_extended
```

Wait 5 seconds, then check:
- Developer Tools → States → `sensor.hastrom_flex_pro_ext`
- Should have attributes: `prices_today`, `prices_tomorrow`, `last_update`

**Test 2 - Optimizer**:
```yaml
service: pyscript.calculate_charging_schedule
```

Wait 5 seconds, then check:
- Developer Tools → States → `pyscript.battery_charging_schedule`
- Should have attributes: `schedule`, `num_charges`, `last_update`

**Test 3 - Executor**:
```yaml
service: pyscript.execute_charging_schedule
```

Check logs immediately for output like:
```
Suche Ladeplan für YYYY-MM-DD HH:00 Uhr (lokal)
```

---

### STEP 5: Check Required Entities

Go through each entity in "Required Entities" list above.

**For each missing entity**:
1. Settings → Devices & Services → Helpers
2. Create Helper → Choose type (Number/Toggle/Text)
3. Set entity_id exactly as listed
4. Set default values as documented

---

### STEP 6: Enable Debug Logging

**configuration.yaml**:
```yaml
logger:
  default: info
  logs:
    custom_components.pyscript: debug
    custom_components.pyscript.file.battery_charging_optimizer: debug
    custom_components.pyscript.file.hastrom_flex_extended: debug
```

Restart Home Assistant, then repeat tests.

---

## What to Provide When Requesting Help

If you need assistance after following this guide, provide:

1. ✅ **Home Assistant Version**
   - Settings → System → Info

2. ✅ **PyScript Version**
   - Settings → Devices & Services → PyScript → Click for details

3. ✅ **Python Version**
   ```bash
   docker exec homeassistant python --version
   ```

4. ✅ **Error Logs**
   - Last 100 lines from logs filtered for "pyscript"
   - Include timestamps

5. ✅ **Service List**
   - Screenshot or list of services starting with "pyscript."

6. ✅ **Entity Status**
   - Confirm which entities from "Required Entities" exist
   - Note which are missing

7. ✅ **Manual Test Results**
   - What happened when you called `pyscript.getprices_extended`?
   - What happened when you called `pyscript.calculate_charging_schedule`?
   - Any error notifications in UI?

8. ✅ **File Locations**
   ```bash
   ls -la /config/pyscript/
   ```

---

## Files Generated for This Diagnosis

1. **diagnostic_pyscript_issues.md** - Detailed technical analysis of potential issues
2. **TROUBLESHOOTING_GUIDE.md** - Step-by-step fixes for each scenario
3. **validate_pyscript.py** - Automated validation script
4. **DIAGNOSIS_SUMMARY.md** - This file (executive summary)

---

## Next Steps

### Immediate Actions:

1. **Get the logs**: Access Home Assistant logs using one of the methods above
2. **Run validation**: Execute `python3 validate_pyscript.py` in this directory
3. **Follow troubleshooting**: Open TROUBLESHOOTING_GUIDE.md and work through checklist
4. **Test manually**: Try calling each service individually and note results

### Expected Timeline:

- **5 minutes**: Get logs and identify error
- **10 minutes**: Apply appropriate fix from troubleshooting guide
- **5 minutes**: Test and verify working

### If Stuck:

- Review all 4 generated documentation files
- Gather information from "What to Provide" section
- Post to Home Assistant Community forum with complete details
- Reference this diagnosis in your post

---

## Technical Notes

### Timezone Handling
Both scripts use `zoneinfo.ZoneInfo("Europe/Berlin")` for timezone awareness. This is correct and follows best practices, but requires:
- Python 3.9+
- Home Assistant 2021.7+

### PyScript Patterns Used
- `@service` decorator for service registration
- `@time_trigger("cron(...)")` for scheduled execution
- `task.executor()` for blocking I/O
- `state.get()` and `state.getattr()` for entity access
- `state.set()` with `new_attributes` for complex data
- `log.info()`, `log.warning()`, `log.error()` for logging

All patterns are correct for PyScript.

### State Management
The optimizer stores schedule in `pyscript.battery_charging_schedule` state with complex attributes. This is the recommended pattern, but monitor size.

### Service Chaining
Scripts call their own services using `pyscript.service_name()` syntax. This should work in PyScript, but alternative is direct function call.

---

## Validation Results

✅ **Syntax**: Valid Python 3
✅ **Structure**: Correct PyScript patterns
✅ **Imports**: Standard library + PyScript built-ins
✅ **Error Handling**: Try-catch blocks present
✅ **Logging**: Comprehensive debug output
⚠️ **Dependencies**: Requires Python 3.9+ for zoneinfo
⚠️ **Entities**: Assumes many helpers exist

---

## Conclusion

The code is **structurally sound** and should work if:
1. PyScript integration is properly configured
2. All required helper entities exist
3. Python version is 3.9+
4. Files are in `/config/pyscript/`

**Most likely issue**: Missing entities or PyScript not loading files.

**Diagnosis confidence**: 85% - Cannot be 100% without live logs

**Recommended action**: Follow STEP 1-6 in troubleshooting steps above, starting with accessing logs.

---

**Generated**: 2025-11-20
**By**: Claude Code diagnostic analysis
**Status**: Ready for user action