Troubleshooting Guide - delize/home-assistant-loggamera-integration GitHub Wiki

Troubleshooting Guide

This comprehensive troubleshooting guide provides solutions for common issues with the Loggamera integration. The integration includes 25+ diagnostic tools to help identify and resolve problems quickly.

🚨 Quick Start - Essential Diagnostic Commands

Before opening any support requests, run these core diagnostic tools:

# 1. Primary diagnostic (run this first for any issue)
python tools/loggamera_diagnostic.py YOUR_API_KEY --verbose

# 2. Complete infrastructure mapping (for device/sensor issues)
python tools/organization_mapper.py YOUR_API_KEY --format json --verbose

# 3. Basic connectivity test (for connection issues)
python tools/test_connection.py YOUR_API_KEY

📋 Common Issues Quick Reference

Issue Type Symptoms Primary Tools Quick Fix
SSL/TLS Certificate CERTIFICATE_VERIFY_FAILED errors diagnose_tls.sh Update CA certificates
Connection Issues "Cannot connect" during setup test_connection.py Check internet/firewall
Access Denied API error: access denied loggamera_diagnostic.py Verify API key permissions
Missing Devices No devices show up organization_mapper.py Check organization access
"Unavailable" Sensors Sensors show as unavailable test_device_counter.py Restart integration
Data Not Updating Sensors don't update monitor_powermeter_updates.py Adjust scan interval
Unknown Sensors Sensors show as "Unknown" validate_sensor_mappings.py Check sensor mappings

🔧 SSL/TLS Certificate Issues

SSL/TLS certificate issues are common, especially in Docker environments.

Symptoms

  • Error messages containing CERTIFICATE_VERIFY_FAILED
  • Error messages about SSL/TLS verification
  • Integration shows "Cannot connect" during setup

Solutions

1. Run the TLS Diagnostic Script (Recommended)

# This script automatically diagnoses and fixes most certificate issues
bash tools/diagnose_tls.sh

2. Manual Certificate Updates

# Update CA certificates in Docker
docker exec -it homeassistant bash -c "apt-get update && apt-get install -y ca-certificates"

# Update Python certifi package
docker exec -it homeassistant bash -c "pip install --upgrade certifi"

3. Create Custom CA Bundle

# Create custom certificate directory
docker exec -it homeassistant bash -c "mkdir -p /etc/ssl/certs/custom && cp /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/custom/cacert.pem"

🌐 Connection Issues

Symptoms

  • "Cannot connect" errors during integration setup
  • Timeout errors in logs
  • Network connectivity problems

Solutions

1. Basic Connectivity Test

python tools/test_connection.py YOUR_API_KEY

2. Network Diagnostics

# Test DNS resolution
docker exec -it homeassistant bash -c "nslookup platform.loggamera.se"

# Test network connectivity
docker exec -it homeassistant bash -c "ping platform.loggamera.se"

# Test HTTPS connectivity
docker exec -it homeassistant bash -c "curl -I https://platform.loggamera.se"

3. Firewall and Network Configuration

  • Ensure outbound connections to platform.loggamera.se on port 443 are allowed
  • Check if your network has proxy settings that might interfere
  • Verify DNS resolution is working correctly

🔐 Access Denied Errors

Symptoms

  • Log entries with "API error: {'Message': 'access denied'}"
  • Integration connects but doesn't show any devices
  • Authentication failures

Solutions

1. API Key Validation

# Test API key and permissions
python tools/loggamera_diagnostic.py YOUR_API_KEY --verbose

2. Organization Access

# Map all accessible organizations
python tools/organization_mapper.py YOUR_API_KEY --format json

3. Common Fixes

  • Verify API key is correct and has proper permissions
  • Check if API key is tied to a specific organization
  • Ensure API key hasn't been revoked or expired
  • Try removing and re-adding the integration

📱 Missing Devices/Entities

Symptoms

  • Integration shows as connected, but no devices/entities appear
  • Some devices appear, but others are missing
  • Devices visible in Loggamera portal but not in Home Assistant

Solutions

1. Complete Device Discovery

# Map all devices across all organizations
python tools/organization_mapper.py YOUR_API_KEY --format markdown --verbose

2. Device Visibility Testing

# Test specific organization access
python tools/test_connection.py YOUR_API_KEY ORGANIZATION_ID

# Comprehensive device testing
python tools/loggamera_diagnostic.py YOUR_API_KEY --verbose

3. Common Fixes

  • Wait a few minutes for device discovery to complete
  • Check if devices are visible in the Loggamera platform
  • Verify correct organization ID is being used
  • Restart Home Assistant if devices still don't appear

📊 Data Update Issues

Symptoms

  • Entities exist but don't update properly
  • Sensor values are stale or incorrect
  • Data updates inconsistently

Solutions

1. Monitor Update Patterns

# Monitor PowerMeter updates over time
python tools/monitor_powermeter_updates.py --api-key YOUR_API_KEY --device-id DEVICE_ID --duration 2

# Analyze update frequency
python tools/analyze_update_frequency.py powermeter_logs/logfile.log

2. Device-Specific Analysis

# Detailed PowerMeter analysis
python tools/analyze_power_meter.py YOUR_API_KEY DEVICE_ID

# Basic device output testing
python tools/basic_powermeter_output.py YOUR_API_KEY DEVICE_ID

3. Configuration Adjustments

  • Adjust scan interval in integration options (default: 60 seconds)
  • Check API quotas and rate limits
  • Verify devices are active and reporting data to Loggamera
  • Note: PowerMeter data typically updates every ~30 minutes

🐳 Docker-Specific Issues

Docker environments have unique challenges related to networking, certificates, and permissions.

Solutions

1. Certificate Path Issues

# Docker certificate diagnostic
docker exec -it homeassistant bash -c "python -c 'import ssl; print(ssl.get_default_verify_paths())'"

2. Network Mode Considerations

  • If using host network mode, ensure proper DNS resolution
  • Check container network configuration
  • Verify outbound connectivity from container

3. Container Rebuilds

# After major Home Assistant updates, reinstall certificates
docker exec -it homeassistant bash -c "apt-get update && apt-get install -y ca-certificates curl"

🛠️ Comprehensive Diagnostic Tools Reference

Core Diagnostic Tools

1. Primary Diagnostic Tool (Always Run First)

python tools/loggamera_diagnostic.py YOUR_API_KEY --verbose

Purpose: Complete API connectivity, device discovery, and functionality testing Use for: Any connectivity, device discovery, or general issues

2. Organization Infrastructure Mapper

python tools/organization_mapper.py YOUR_API_KEY --format json --verbose
python tools/organization_mapper.py YOUR_API_KEY --format markdown --output mapping.md

Purpose: Maps ALL devices across ALL organizations with complete sensor discovery Use for: Missing devices/sensors, sensor mapping validation, infrastructure overview

3. Basic Connectivity Test

python tools/test_connection.py YOUR_API_KEY [ORGANIZATION_ID]

Purpose: Basic API connectivity with SSL/TLS diagnostics Use for: Connection problems, SSL issues, authentication problems

API Testing Tools

4. API Explorer

python tools/loggamera_api_explorer.py YOUR_API_KEY ENDPOINT --device-id DEVICE_ID --verbose

Examples:

# Test Organizations endpoint
python tools/loggamera_api_explorer.py YOUR_API_KEY Organizations

# Test device endpoints
python tools/loggamera_api_explorer.py YOUR_API_KEY PowerMeter --device-id 12345
python tools/loggamera_api_explorer.py YOUR_API_KEY RawData --device-id 67890

5. Basic API Test

python tools/api_test.py YOUR_API_KEY

Purpose: Quick API functionality validation

Sensor Mapping Tools

6. Sensor Mapping Validation

python tools/validate_sensor_mappings.py

Purpose: Tests ALL sensor mappings, identifies unmapped sensors, suggests new mappings Use for: Missing sensors, "Unknown" sensors, sensor coverage validation

7. Coverage Testing

python tools/check_actual_coverage.py          # Real coverage using integration mappings
python tools/test_coverage_improvement.py      # Coverage improvement analysis
python tools/final_coverage_test.py           # Final coverage validation

Device-Specific Tools

8. PowerMeter Tools

python tools/analyze_power_meter.py YOUR_API_KEY DEVICE_ID
python tools/basic_powermeter_output.py YOUR_API_KEY DEVICE_ID
python tools/test_powermeter.py YOUR_API_KEY

9. PowerMeter Update Monitoring

python tools/monitor_powermeter_updates.py --api-key YOUR_API_KEY --device-id DEVICE_ID --interval 60 --duration 24
python tools/analyze_update_frequency.py powermeter_logs/logfile.log

10. HeatMeter Tools

python tools/test_heatmeter_api.py
python tools/test_heatmeter_support.py

Integration-Specific Tools

11. Organization Sensor Testing

python tools/test_device_counter.py
python tools/test_device_counter_simple.py
python tools/test_user_count.py

Use for: Organization sensors showing as "Unavailable" or incorrect values

12. Integration Validation

python tools/test_integration_logs.py
python tools/validate_fix.py

Home Assistant Configuration Tools

13. Configuration Helper

python tools/ha_sensor_config_helper.py YOUR_API_KEY DEVICE_ID

Purpose: Generates YAML configuration for dashboards and energy monitoring

Network and SSL Tools

14. TLS/SSL Diagnostics

bash tools/diagnose_tls.sh

Purpose: Comprehensive SSL certificate diagnostics and fixes

15. Insecure API Client (Debug Only)

python tools/api_client_insecure.py YOUR_API_KEY

⚠️ Use only for debugging SSL issues

📝 Creating Support Requests

Required Information

When opening a GitHub issue, include:

  1. Integration Version: Found in HACS or manifest.json
  2. Home Assistant Version: Settings > System > Repairs
  3. Installation Method: HACS, Manual, etc.

Essential Diagnostic Output

Always include output from:

# 1. Primary diagnostic (Required)
python tools/loggamera_diagnostic.py YOUR_API_KEY --verbose > diagnostic_output.txt 2>&1

# 2. Organization mapping (For device/sensor issues)
python tools/organization_mapper.py YOUR_API_KEY --format json > organization_mapping.json 2>&1

Home Assistant Debug Logs

Enable debug logging:

logger:
  default: warning
  logs:
    custom_components.loggamera: debug

Tool-Specific Troubleshooting

For Connection Issues:

python tools/test_connection.py YOUR_API_KEY
python tools/loggamera_diagnostic.py YOUR_API_KEY --verbose
bash tools/diagnose_tls.sh

For Missing Devices/Sensors:

python tools/organization_mapper.py YOUR_API_KEY --format json
python tools/validate_sensor_mappings.py
python tools/loggamera_diagnostic.py YOUR_API_KEY --verbose

For Data Update Issues:

python tools/monitor_powermeter_updates.py --api-key YOUR_API_KEY --device-id DEVICE_ID --duration 2
python tools/analyze_power_meter.py YOUR_API_KEY DEVICE_ID

For "Unavailable" Sensors:

python tools/test_device_counter.py
python tools/test_integration_logs.py
python tools/validate_fix.py

🔒 Security Note

When sharing diagnostic output:

  • Replace your API key with YOUR_API_KEY_HERE
  • Replace organization IDs with YOUR_ORG_ID_HERE
  • Replace device IDs with generic numbers
  • Remove specific device names or identifiers

🆘 Still Having Issues?

  1. Check GitHub Issues for similar problems
  2. Review the API Issues and Workarounds wiki page
  3. Create a new issue with complete diagnostic output
  4. Include detailed problem description and steps to reproduce

The diagnostic tools provide comprehensive information to help developers quickly identify and resolve issues. Please use them before requesting support!