Installation and Setup - delize/home-assistant-loggamera-integration GitHub Wiki

Installation and Setup

This guide covers installing and configuring the Loggamera integration in Home Assistant.

🚀 Quick Installation

Prerequisites

  • Home Assistant 2023.1 or later
  • HACS (Home Assistant Community Store) installed
  • Loggamera API key (how to get one)

Installation Methods

Method Difficulty Recommended For
HACS Catalog ⭐ Easy Most users
HACS Custom Repository ⭐⭐ Medium Beta testing
Manual Installation ⭐⭐⭐ Advanced Developers

📦 HACS Catalog Installation

Recommended method for most users

Step 1: Install via HACS

  1. Open HACS in your Home Assistant instance
  2. Go to Integrations
  3. Search for "Loggamera"
  4. Click "Download" on the Loggamera integration
  5. Restart Home Assistant

Step 2: Add Integration

  1. Go to Settings → Devices & Services
  2. Click "+ Add Integration"
  3. Search for "Loggamera"
  4. Click on Loggamera integration

Step 3: Configuration

  1. Enter your Loggamera API key
  2. Optionally adjust scan interval (default: 20 minutes)
  3. Click "Submit"

The integration will automatically:

  • Discover your organization(s)
  • Find all devices
  • Create sensors for each device
  • Set up organization monitoring sensors

🔧 HACS Custom Repository

For beta testing or latest features

Step 1: Add Custom Repository

  1. Open HACS in your Home Assistant instance
  2. Go to Integrations
  3. Click the three dots in the top right corner
  4. Select "Custom repositories"
  5. Add repository URL: https://github.com/delize/home-assistant-loggamera-integration
  6. Select "Integration" as the category
  7. Click "Add"

Step 2: Install Integration

  1. Search for "Loggamera" in HACS
  2. Click "Download"
  3. Restart Home Assistant

Step 3: Configure

Follow the same configuration steps as HACS Catalog Installation

📁 Manual Installation

For developers and advanced users

Step 1: Download Files

# Download latest release
wget https://github.com/delize/home-assistant-loggamera-integration/releases/latest/download/loggamera.zip

# Or clone repository
git clone https://github.com/delize/home-assistant-loggamera-integration.git

Step 2: Copy Files

# Extract and copy to Home Assistant
unzip loggamera.zip
cp -r custom_components/loggamera /config/custom_components/

# Or if cloned
cp -r home-assistant-loggamera-integration/custom_components/loggamera /config/custom_components/

Step 3: Restart and Configure

  1. Restart Home Assistant
  2. Follow configuration steps from HACS installation

🔑 Obtaining API Key

From Loggamera Portal

  1. Log in to your Loggamera portal account
  2. Navigate to API settings or Developer section
  3. Generate new API key or copy existing key
  4. Save the key securely - you'll need it for configuration

API Key Requirements

  • Must have access to your organization(s)
  • Should have read permissions for devices and data
  • May require organization-specific permissions

Note: If you don't see API settings in your portal, contact Loggamera support to enable API access for your account.

⚙️ Configuration Options

Basic Configuration

Setting Default Description
API Key Required Your Loggamera API key
Scan Interval 1200 seconds (20 min) How often to update sensor data

Advanced Configuration

Scan Interval Recommendations

Device Type Recommended Interval Reason
PowerMeter 20-30 minutes API limitation (~30 min updates)
RoomSensor 5-15 minutes Real-time environmental data
WaterMeter 30-60 minutes Infrequent consumption changes
HeatMeter 15-30 minutes Heating system monitoring
Organization 20-30 minutes Infrastructure monitoring

Configuration via YAML (Optional)

The integration uses UI configuration, but you can reference it in automations:

# Example: Reference integration in automations
automation:
  - alias: "High Power Usage Alert"
    trigger:
      platform: numeric_state
      entity_id: sensor.loggamera_DEVICE_ID_current_power_consumption
      above: 5.0
    action:
      service: notify.mobile_app
      data:
        message: "High power usage: {{ states('sensor.loggamera_DEVICE_ID_current_power_consumption') }} kW"

🏠 Post-Installation Setup

Verify Installation

1. Check Integration Status

  1. Go to Settings → Devices & Services
  2. Find Loggamera integration
  3. Verify status shows "Configured"
  4. Check for any error messages

2. Verify Devices and Sensors

  1. Go to Settings → Devices & Services → Loggamera
  2. Check that your devices are listed
  3. Click on each device to see its sensors
  4. Verify sensors have current values (may take a few minutes)

3. Run Diagnostic Test

# Test API connectivity and device discovery
python /config/custom_components/loggamera/tools/test_connection.py YOUR_API_KEY

Enable Additional Sensors

RawData Sensors (Optional)

Many sensors are disabled by default to prevent entity spam:

  1. Go to Settings → Devices & Services → Loggamera
  2. Click on a device
  3. Look for disabled sensors (greyed out)
  4. Click "Enable" for sensors you want to use

Organization Sensors

Organization sensors are enabled by default and provide:

  • Total device count
  • Organization hierarchy information
  • User and member counts

Energy Dashboard Integration

For PowerMeter Devices

# Add to Energy Dashboard
energy:
  sources:
    - type: grid
      flow_from:
        - sensor.loggamera_DEVICE_ID_total_energy_consumption

Setup Steps

  1. Go to Settings → Dashboards → Energy
  2. Click "Add Energy Source"
  3. Select "Grid consumption"
  4. Choose your PowerMeter total energy sensor
  5. Save configuration

🔍 Troubleshooting Installation

Common Installation Issues

Integration Not Found in HACS

Problem: Can't find Loggamera in HACS search Solutions:

  • Ensure HACS is properly installed and updated
  • Try adding as custom repository
  • Clear HACS cache and refresh

SSL/TLS Certificate Errors

Problem: CERTIFICATE_VERIFY_FAILED during setup Solutions:

# Run SSL diagnostic tool
bash /config/custom_components/loggamera/tools/diagnose_tls.sh

# Or manually update certificates
docker exec -it homeassistant bash -c "apt-get update && apt-get install -y ca-certificates"

API Key Authentication Failed

Problem: "Cannot connect" or "Invalid API key" errors Solutions:

  • Verify API key is correct and has proper permissions
  • Check if API key is organization-specific
  • Test API key with diagnostic tool:
python /config/custom_components/loggamera/tools/test_connection.py YOUR_API_KEY

No Devices Found

Problem: Integration connects but no devices appear Solutions:

  • Wait 5-10 minutes for device discovery
  • Check organization access permissions
  • Run comprehensive diagnostic:
python /config/custom_components/loggamera/tools/loggamera_diagnostic.py YOUR_API_KEY --verbose

Getting Installation Help

Diagnostic Information for Support

If you need help, provide:

  1. Home Assistant version
  2. Integration version (from HACS)
  3. Installation method used
  4. Error messages from logs
  5. Diagnostic output:
python /config/custom_components/loggamera/tools/test_connection.py YOUR_API_KEY > connection_test.txt 2>&1

Debug Logging

Enable debug logging for detailed troubleshooting:

# configuration.yaml
logger:
  default: warning
  logs:
    custom_components.loggamera: debug

🎛️ Configuration Management

Updating Configuration

Via UI (Recommended)

  1. Go to Settings → Devices & Services → Loggamera
  2. Click "Configure" on the integration
  3. Modify scan interval or other settings
  4. Click "Submit"

Reconfiguration

To change API key or major settings:

  1. Remove the integration from Devices & Services
  2. Add integration again with new settings
  3. Devices and entities will be recreated

Multiple Organizations

Single API Key, Multiple Organizations

  • Integration automatically discovers all accessible organizations
  • Devices from all organizations appear in single integration
  • Organization sensors show hierarchy information

Multiple API Keys

For separate API keys:

  1. Add integration multiple times
  2. Use different API key for each instance
  3. Each instance will show as separate integration

📊 Optimization and Performance

Scan Interval Optimization

PowerMeter Devices

  • Default: 20 minutes (1200 seconds)
  • API Limitation: ~30 minutes actual update frequency
  • Recommendation: Don't set below 15 minutes

Real-time Devices (RoomSensor)

  • Default: 20 minutes
  • Can reduce to: 5-10 minutes for environmental monitoring
  • Consider: Increased API usage

Resource Usage

  • CPU: Minimal impact
  • Network: Depends on scan interval and device count
  • Storage: Standard Home Assistant entity storage

Performance Monitoring

Monitor API Usage

# Monitor update patterns
python /config/custom_components/loggamera/tools/monitor_powermeter_updates.py --api-key YOUR_API_KEY --device-id YOUR_DEVICE_ID --duration 4

Integration Health

  • Check integration status in Settings → Devices & Services
  • Monitor System → Logs for errors
  • Use diagnostic tools for health checks

🔄 Updates and Maintenance

Updating the Integration

Via HACS (Recommended)

  1. HACS → Integrations
  2. Find Loggamera integration
  3. Click "Update" when available
  4. Restart Home Assistant

Update Notifications

Backup and Restore

Before Major Updates

# Backup integration configuration
cp -r /config/custom_components/loggamera /config/backups/loggamera_backup_$(date +%Y%m%d)

Entity Registry

Home Assistant automatically maintains entity registry entries, so devices and entities will persist through updates.

For complete installation and setup support, see the Troubleshooting Guide and Diagnostic Tools Reference.