Installation using HACS (Recommended) - HAEdwin/homeassistant-apsystems_ecu_reader GitHub Wiki

This guide will walk you through installing the APsystems ECU Reader custom integration for Home Assistant using HACS (Home Assistant Community Store).

Prerequisites

Before installing this integration, ensure you have:

  1. Home Assistant installed and running (version 2023.1 or later recommended)
  2. HACS (Home Assistant Community Store) installed and configured
  3. APsystems ECU device on your local network
  4. The IP address of your APsystems ECU device

What This Integration Provides

The APsystems ECU Reader integration allows you to monitor your APsystems solar power system directly from Home Assistant. It provides:

  • Real-time monitoring of inverter power output
  • Individual inverter status and performance metrics
  • ECU device information and diagnostics
  • Power generation statistics and historical data
  • System health monitoring with alerts
  • ECU management functions (reboot, settings)

Supported Devices

  • ECU Models: ECU-R, ECU-R-Pro, ECU-B, ECU-C, ECU-3
  • Inverter Series: YC500, YC600, YC1000, DS3, QS1, QT2

Step 1: Add Custom Repository

  1. Open Home Assistant and navigate to HACS
  2. In HACS, search for "APsystems ECU Reader"
  3. Click Download

Step 2: Restart Home Assistant

  1. Go to Settings > System > Restart
  2. Click RESTART and wait for Home Assistant to come back online

Configuration

Step 1: Add the Integration

  1. Navigate to Settings > Devices & Services
  2. Click + ADD INTEGRATION
  3. Search for "APsystems ECU Reader"
  4. Click on the integration to start configuration

Step 2: Configure Connection Settings

Fill in the required information:

Basic Settings

  • ECU Host/IP Address: The IP address of your APsystems ECU device
    • Example: 192.168.1.100
    • You can find this in your router's device list or ECU web interface
  • Scan Interval: How often to poll the ECU for data (in seconds)
    • Default: 300 (5 minutes)
    • Minimum: 30 seconds
    • Recommended: 60-300 seconds

Advanced Settings (Optional)

  • Port Retries: Number of connection retry attempts
    • Default: 3
    • Range: 1-10
  • Cache Reboot: Enable automatic ECU reboot on communication issues
    • Default: Enabled
  • Show Graphs: Enable graphical data representation
    • Default: Enabled

WiFi Credentials (Optional)

If you want to manage ECU WiFi settings:

  • WiFi SSID: Your network name
  • WiFi Password: Your network password

Step 3: Complete Setup

  1. Click SUBMIT to save the configuration
  2. The integration will attempt to connect to your ECU
  3. If successful, you'll see a confirmation message
  4. Click FINISH to complete the setup

Verification

Check Device Creation

  1. Go to Settings > Devices & Services
  2. Look for APsystems ECU Reader in the integrations list
  3. Click on it to see your ECU device and connected inverters

Verify Entities

The integration creates several types of entities:

Sensors

  • ECU Power: Total system power output
  • ECU Energy Today: Daily energy production
  • ECU Energy Lifetime: Lifetime energy production
  • Individual Inverter Power: Power output per inverter
  • Individual Inverter Voltage: Voltage per inverter channel
  • Signal Strength: Communication signal quality

Binary Sensors

  • ECU Online Status: ECU connectivity status
  • Individual Inverter Online: Per-inverter connectivity

Switches

  • Inverter Enable/Disable: Control individual inverters
  • Zero Export Mode: Enable/disable zero export functionality

Numbers

  • Max Power Settings: Adjust maximum power output per inverter

Buttons

  • ECU Reboot: Remotely reboot the ECU device

Troubleshooting

Common Issues

1. ECU Not Found / Connection Failed

Symptoms: Integration setup fails with connection error

Solutions:

  • Verify the ECU IP address is correct
  • Ensure ECU is powered on and connected to your network
  • Check that Home Assistant can reach the ECU (same network/VLAN)
  • Try pinging the ECU from your Home Assistant system
  • Verify port 8899 is not blocked by firewall

2. No Data from Inverters

Symptoms: ECU connects but no inverter data appears

Solutions:

  • Check if inverters are powered and producing power
  • Verify inverters are properly connected to ECU
  • Check ECU web interface to confirm inverters are detected
  • Restart the integration from Settings > Devices & Services

3. Intermittent Connection Issues

Symptoms: Integration works sometimes but disconnects frequently

Solutions:

  • Increase the scan interval to reduce ECU load
  • Enable "Cache Reboot" option
  • Check ECU power supply stability
  • Verify network connectivity is stable

4. Integration Not Appearing in HACS

Symptoms: Can't find the integration in HACS

Solutions:

  • Ensure you've added the custom repository correctly
  • Refresh HACS repository list
  • Check that the repository URL is correct
  • Clear HACS cache and restart Home Assistant

Log Analysis

To enable debug logging for troubleshooting:

  1. Add this to your configuration.yaml: 
    logger:
  default: warning
  logs:
    custom_components.APsystems_ecu_reader: debug
  2. Restart Home Assistant
  3. Check Settings > System > Logs for detailed information

Getting Help

If you continue to experience issues:

  1. Check the GitHub Issues page
  2. Review existing issues for similar problems
  3. Create a new issue with:
    • Home Assistant version
    • Integration version
    • ECU model and firmware version
    • Inverter models and quantities
    • Relevant log entries
    • Configuration details (without sensitive information)

Updates

  1. HACS will notify you when updates are available
  2. Go to HACS > Integrations
  3. Find APsystems ECU Reader and click UPDATE
  4. Restart Home Assistant after the update

Uninstallation

  1. Remove the integration from Settings > Devices & Services
  2. Delete entities if prompted
  3. Remove via HACS or delete the custom_components/APsystems_ecu_reader/ folder
  4. Restart Home Assistant
  5. Clean up any related dashboard cards or automations