Troubleshooting¶

This section helps you diagnose and resolve common issues with aiohomematic and the Homematic(IP) Local integration.

Quick Diagnostic Flowchart¶

flowchart TD
    START([Issue Detected]) --> Q1{CCU WebUI<br/>accessible?}
    Q1 -->|No| FIX1[Check CCU power/network]
    Q1 -->|Yes| Q2{Can login<br/>with same creds?}
    Q2 -->|No| FIX2[Fix credentials]
    Q2 -->|Yes| Q3{Integration<br/>loads?}
    Q3 -->|No| FIX3[Check HA logs]
    Q3 -->|Yes| Q4{Events<br/>received?}
    Q4 -->|No| FIX4[Check callback config]
    Q4 -->|Yes| Q5{Specific device<br/>issue?}
    Q5 -->|Yes| FIX5[Check device/entity]
    Q5 -->|No| DONE([Working normally])

    FIX1 --> START
    FIX2 --> START
    FIX3 --> START
    FIX4 --> START
    FIX5 --> START

Quick Diagnostic Checklist¶

Before diving into specific issues, verify these basics:

Common Issues by Category¶

Connection Problems¶

• CCU not reachable
• Authentication failures
• Callback/event issues
• Docker networking

Device Issues¶

• Device not appearing
• Entity shows "unavailable"
• Values not updating
• Button events not working
• Missing parameters after firmware update

Performance Issues¶

• Slow startup
• High CPU usage
• Frequent reconnections

Connection Problems¶

CCU Not Reachable¶

Symptoms:

• Integration fails to start
• "Connection refused" or "Timeout" errors in logs

Solutions:

1. Verify CCU IP address is correct
2. Check if CCU is powered on and fully booted
3. Test connectivity: ping your-ccu-ip
4. Verify firewall allows required ports (see Ports Reference)

Authentication Failures¶

Symptoms:

• "Authentication failed" error
• "Invalid credentials" in logs

Solutions:

1. Verify username is exactly as shown in CCU (case-sensitive)
2. Check password contains only allowed characters: A-Z, a-z, 0-9, .!$():;#-
3. Ensure user has administrator privileges in CCU
4. Try logging into CCU WebUI with same credentials

Callback Issues¶

Symptoms:

• Devices appear but values don't update
• "No events received" warnings
• State changes in CCU not reflected in HA

Solutions:

1. Verify CCU can reach Home Assistant (check firewall)
2. For Docker: Set callback_host to Docker host IP
3. Check callback_port_xml_rpc is not blocked
4. Verify no other integration uses same callback port

Docker Networking¶

Symptoms:

• Integration works initially but loses connection
• Events not received in Docker environment

Solutions:

Device Issues¶

Device Not Appearing¶

Symptoms:

• Paired device in CCU but not in HA
• Device visible in CCU but missing from HA devices

Solutions:

1. Check Settings → System → Repairs for pending device notifications
2. Reload the integration (Settings → Devices & Services → Reload)
3. Verify device is paired in CCU and shows online
4. Check if correct interface is enabled (HmIP-RF, BidCos-RF, etc.)

Entity Unavailable¶

Symptoms:

• Entity shows "unavailable" state
• Gray entity card in dashboard

Solutions:

1. Entity might be disabled by default → Enable in entity settings
2. Check device battery if wireless
3. Verify device is in range of CCU
4. Check RSSI values (see RSSI Fix)

Values Not Updating¶

Symptoms:

• Entity value doesn't change when device state changes
• Manual refresh required to see updates

Solutions:

1. Check callback configuration (see Callback Issues)
2. For CUxD/CCU-Jack: Enable MQTT for push updates
3. Verify device sends events (some devices only send on significant changes)

Button Events Not Working¶

Symptoms:

• Button press doesn't trigger automation
• No events in HA developer tools

Solutions:

For HomematicIP remotes:

1. Create central links: Use action homematicip_local.create_central_links
2. Or activate in CCU: Devices → Click "+" → Channel → Activate

For classic Homematic buttons:

• Should work automatically after pairing

Performance Issues¶

Slow Startup¶

Symptoms:

• Integration takes long time to initialize
• Many "Fetching..." messages in logs

Solutions:

1. First start after update is slower (cache rebuild) - this is normal
2. Check network latency to CCU
3. Reduce number of enabled interfaces if not all needed
4. Consider disabling system variable/program scan if not used

High CPU Usage¶

Symptoms:

• Home Assistant CPU spikes related to integration

Solutions:

1. Increase system variable scan interval (default 30s, try 60s+)
2. Reduce number of enabled entities
3. Check for rapid value changes causing event floods

Frequent Reconnections¶

Symptoms:

• "Connection lost" / "Reconnected" messages in logs
• Devices intermittently unavailable

Solutions:

1. Check network stability between HA and CCU
2. Verify CCU is not overloaded
3. Check for IP address changes (use static IP or hostname)
4. Review CCU logs for errors

Ports Reference¶

Getting Debug Information¶

Home Assistant Logs¶

1. Go to Settings → System → Logs
2. Filter for homematicip_local or aiohomematic
3. Enable debug logging if needed:

# configuration.yaml
logger:
  default: info
  logs:
    aiohomematic: debug
    custom_components.homematicip_local: debug

Download Diagnostics¶

1. Go to Settings → Devices & Services
2. Find Homematic(IP) Local integration
3. Click the three dots menu → Download Diagnostics
4. Attach to bug reports

Check Integration Version¶

1. Go to Settings → Devices & Services
2. Click on Homematic(IP) Local
3. Version shown at top of page

Further Resources¶

• Detailed Troubleshooting Guide
• Troubleshooting Flowchart
• RSSI Fix Guide
• CUxD and CCU-Jack

Still Need Help?¶

1. Search existing issues
2. Ask in GitHub Discussions
3. Open a new issue with:
4. Home Assistant version
5. Integration version
6. CCU type and firmware version
7. Relevant logs
8. Steps to reproduce