README.md

Huawei Solar Modbus to Home Assistant via MQTT + Auto-Discovery

🇬🇧 English | 🇩🇪 Deutsch

67 Essential Registers • 68 Entities • Optional MQTT Heartbeat • 30s Polling
Changelog: CHANGELOG.md

⚠️ IMPORTANT: Single Modbus Connection Limit Huawei inverters allow only ONE active Modbus TCP connection.

• ✅ Remove any other Huawei Solar integrations (wlcrs/huawei_solar, HACS, etc.)
• ✅ Disable monitoring tools and apps with Modbus access
• ✅ Note: FusionSolar Cloud may show "Abnormal communication" - this is expected

Features

• Automatic Slave ID Detection: Tries common values (1, 2, 100) automatically
• Modbus TCP → MQTT: 68 entities with Auto-Discovery
• Complete Monitoring: Battery, PV (1-4), Grid (3-phase), Energy counters
• Total Increasing Filter: Prevents false counter resets in energy statistics
• Auto MQTT Configuration: Automatically uses Home Assistant MQTT credentials
• Performance Diagnostics: Per-register timing analysis at DEBUG level to identify bottlenecks
• TRACE Log Level: Ultra-detailed debugging with Modbus byte arrays
• Comprehensive Test Suite: 89% code coverage
• Performance: ~2-5s read cycle, configurable poll interval (30-60s recommended)
• Cross-Platform: All major architectures (aarch64, amd64, armhf, armv7, i386)
• Multi Architecture: Home Assistant add-on builds via explicit build.yaml base image mapping

🚀 Quick Start

1. 
2. Install "huABus | Huawei Solar Modbus to MQTT"
3. Minimal Configuration:

   modbus_host: 192.168.1.100
   modbus_auto_detect_slave_id: true
   log_level: INFO
   

4. Start the addon → Settings → Devices & Services → MQTT → "Huawei Solar Inverter"

EVCC Integration (No Modbus Proxy!)

huABus publishes all data to a single MQTT topic (huawei-solar), enabling direct EVCC integration without Modbus proxy or conflicts.

Requirement: Activated MQTT in evcc HA Addon (evcc UI → Settings → MQTT)

Grid Meter:

power:
  source: mqtt
  topic: huawei-solar
  jq: "(.meter_power_active * -1)"

Solar Meter:

power:
  source: mqtt
  topic: huawei-solar
  jq: ".power_input"

Battery (optional):

power:
  source: mqtt
  topic: huawei-solar
  jq: "(.battery_power * -1)"
soc:
  source: mqtt
  topic: huawei-solar
  jq: ".battery_soc"
capacity: 10

Comparison: wlcrs/huawei_solar vs. This Addon

Feature	wlcrs/huawei_solar (Integration)	This Addon (MQTT Bridge)
Battery control	✅	❌ (read-only)
MQTT-native	❌	✅
Auto Slave ID detection	❌	✅
Total Increasing filter	❌	✅
External integrations	Limited	✅ (EVCC, Node-RED, Grafana)
Error tracking	Basic	Advanced

Both share the same limitation - only ONE Modbus connection. To use both simultaneously, you need a Modbus Proxy.

Screenshots

Configuration

• Modbus Host: Inverter IP address (e.g. 192.168.1.100)
• Modbus Port: Default: 502
• Auto-detect Slave ID: Default: true (tries 1, 2, 100 automatically)
• Slave ID (manual): Only used when auto-detection disabled
• MQTT Broker: Default: core-mosquitto (leave empty for auto-config)
• MQTT Port: Default: 1883
• MQTT Username/Password: Optional (leave empty to use HA MQTT credentials)
• MQTT Topic: Default: huawei-solar
• Log Level: TRACE | DEBUG | INFO (recommended) | WARNING | ERROR
• Status Timeout: Default: 180s
• Poll Interval: Default: 30s (recommended: 30-60s)

Troubleshooting

Multiple Modbus connections (most common!): Disable all other Huawei integrations and monitoring tools. Only ONE connection allowed.

All Slave IDs fail: Enable Modbus TCP in inverter settings, verify IP address, check firewall.

MQTT Errors: Set broker to core-mosquitto, leave credentials empty.

Logs: Addon → Huawei Solar Modbus to MQTT → Log Tab
Debug Mode: Set log_level: DEBUG

Latest Updates

See CHANGELOG.md for detailed release notes.

• ✅ v1.9.0: Performance diagnostics with per-register timing analysis at DEBUG level
• ✅ v1.8.5: Added multi-architecture build configuration and simplified the Dockerfile
• ✅ v1.8.4: Fix poll interval not being respected in main loop
• ✅ v1.8.3: Fix intermittent Slave ID auto-detection failure (Request cancelled outside library)
• ✅ v1.8.2: CI migration to uv (40% faster builds)
• ✅ v1.8.1: Fix for Home Assistant 2025.1 Modbus slave ID handling
• ✅ v1.8.0: Automatic Slave ID detection

Credits

Based on: mjaschen/huawei-solar-modbus-to-mqtt
Uses library: wlcrs/huawei-solar-lib
Developed by: arboeh | License: MIT