Debug Mode Guide - HAEdwin/homeassistant-apsystems_ecu_reader GitHub Wiki

Why Debug Logs are Essential

When troubleshooting issues with the APsystems ECU Reader integration, debug logs provide critical information that helps developers understand:

  1. Communication patterns between Home Assistant and your ECU
  2. Raw data responses from the ECU that may reveal protocol issues
  3. Parsing errors or unexpected data formats
  4. Timing issues related to network connectivity
  5. Hardware-specific behaviors based on ECU model and firmware

Debug logs are often the only way to diagnose complex issues, especially those related to specific ECU models or firmware versions.

Privacy Considerations

When sharing logs, it's important to protect your privacy by removing the last 7 digits of your ECU ID and Inverter ID. This is necessary because:

  • The ECU ID is a unique identifier for your specific device
  • While the first digits identify the model type (e.g., "2162" for ECU-R-Pro), the complete ID is unique to your installation
  • The full ID could potentially be used for unauthorized access to your device
  • The model type (first digits) is sufficient for troubleshooting most issues

Enabling Debug Mode

To enable debug logging for the APsystems ECU Reader integration:

  • Go to Settings > Devices & Services
  • Choose the APsystems ECU Reader integration
  • Choose the ⋮ Kebab Menu – vertical three dots menu on top right
  • Next Enable debug logging

Now let the log running for at least 10 minutes, then you can stop it again from the same integration page.

Sharing Logs Safely

When sharing logs:

  1. Look for lines containing your ECU ID (typically starting with "215" or "2162")
  2. Replace the last 7 digits with "XXXXXXX" (e.g., "2162XXXXXXX")
  3. Check for any other sensitive information like IP addresses
  4. Share the logs in a GitHub issue or appropriate support channel

What the Debug Logs Reveal

Debug logs will show:

  • Raw hexadecimal data from your ECU
  • Inverter model detection (using INVERTER_MODEL_MAP.get)
  • Signal strength and connection quality
  • Power production data parsing
  • Communication retry attempts
  • Cache usage information

This information is invaluable for diagnosing issues and improving the integration. By providing properly sanitized debug logs, you help developers understand and fix issues while protecting your privacy.