⚠️ BETA - Use at your own risk! This integration is currently in beta testing. Some features may not work as expected. Please report any issues you encounter.
A modular, template-based Modbus Manager for Home Assistant with predefined device templates for popular energy devices.
-
Install HACS (if not already installed):
- Go to HACS and follow the installation instructions
- Restart Home Assistant after installation
-
Add this repository to HACS:
- Open HACS in your Home Assistant sidebar
- Go to Integrations
- Click the three dots menu (⋮) in the top right
- Select Custom repositories
- Add repository URL:
https://github.com/TCzerny/ha-modbus-manager - Set category to Integration
- Click Add
-
Install the integration:
- Search for "Modbus Manager" in HACS Integrations
- Click Install
- Restart Home Assistant
-
Add the integration:
- Go to Settings → Devices & Services
- Click Add Integration
- Search for "Modbus Manager"
- Follow the configuration wizard
-
Download the latest release from the Releases page
-
Copy the integration:
- Extract the downloaded file
- Copy the
modbus_managerfolder to yourcustom_componentsdirectory - Your structure should look like:
config/custom_components/modbus_manager/
-
Restart Home Assistant
-
Add the integration:
- Go to Settings → Devices & Services
- Click Add Integration
- Search for "Modbus Manager"
- Follow the configuration wizard
- Predefined Device Templates: Ready-to-use templates for popular devices
- Template-based Configuration: Devices are defined via YAML templates
- Multi-Step Configuration Flow: Intuitive step-by-step device setup
- Dynamic Template Configuration: Automatic sensor filtering based on device parameters
- Model Selection: Automatic configuration based on device model selection
- Aggregate Sensors: Aggregation of sensors across multiple devices
- Calculated Sensors: Template-based calculations with Jinja2
- Options Flow: Post-configuration of aggregate hubs via the UI
- Template Reload: Update templates without losing configuration
- Modular Architecture: Easily extensible for new device types
- Home Assistant Integration: Fully integrated into the HA UI
-
Sungrow SHx Series - Complete template with all sensors and controls
- Dynamic Configuration: Supports all 36 SHx models with automatic filtering
- Multi-Step Setup: Connection parameters → Dynamic configuration
- Battery Options: None, Standard Battery, SBR Battery
- Battery management: SOC, charging/discharging, temperature monitoring
- MPPT tracking: 1-3 MPPT trackers with power calculations
- String tracking: 0-4 strings with individual monitoring
- Grid interaction: Import/export, phase monitoring, frequency
- Calculated sensors: Efficiency, power balance, signed battery power
- Full Modbus register mapping: Based on mkaiser's comprehensive implementation
- Firmware compatibility: Automatic sensor parameter adjustment
- Connection types: LAN and WINET support with register filtering
- Float conversion: Full IEEE 754 32-bit and 64-bit floating-point support
-
Sungrow SG Series - Dynamic template with model selection
- 2-Step Configuration: Connection parameters → Model selection
- Model Selection: Automatic configuration based on selected model
- Supported Models: SG3.0RS, SG4.0RS, SG5.0RS, SG6.0RS, SG8.0RS, SG10RS, SG3.0RT, SG4.0RT, SG5.0RT, SG6.0RT
- Automatic Filtering: Phases, MPPT, Strings configured automatically
- Firmware Support: SAPPHIRE-H firmware compatibility
- Connection Types: LAN and WINET support
- Compleo eBox Professional - Complete EV charger template
- 3-phase charging control
- Current and power monitoring
- Fallback current settings
- Cable status and charging control
- SMA - Sunny Boy, Tripower, Home Storage
- Fronius - GEN24, Tauro
- Huawei - Luna, FusionSolar
- SolarEdge - HD Wave, StorEdge
- Kostal - Piko, Plenticore
- Growatt - MIN, MAX series
- Victron - MultiPlus, Quattro
The Modbus Manager supports three types of value processing for converting raw register values to human-readable text:
Direct 1:1 mapping of numeric values to text strings. Used for status codes, error codes, and operating modes.
# Example: Operating mode mapping
map:
0: "Off"
1: "On"
2: "Standby"
3: "Error"
64: "Running (normal operation)"Bit-based evaluation where multiple flags can be active simultaneously. Used for status registers with multiple bits or alarm flags.
# Example: Status register with multiple flags
flags:
0: "Alarm 1"
1: "Alarm 2"
2: "Warning"
3: "Maintenance"
4: "System OK"Result: If register value = 5 (binary: 101), the result would be: "Alarm 1, Warning"
Dropdown options for Select controls. Used for configuration options and selection menus.
# Example: Configuration options
options:
0: "Auto"
1: "Manual"
2: "Schedule"
3: "Emergency"All entity types (Sensors, Select, Number, Switch, Binary Sensor) process values in this order:
- Map (if defined)
- Flags (if no map defined)
- Options (if no map or flags defined)
Each device template includes:
# Example: Sungrow SHx Template
name: "Sungrow SHx Inverter"
version: 1
description: "Sungrow SHx Series Solar Inverter"
manufacturer: "Sungrow"
model: "SHx Series"
# Raw Modbus sensors
sensors:
- name: "Battery Level"
unique_id: "battery_level"
address: 5000
input_type: "holding"
data_type: "uint16"
group: "PV_battery_power"
# ... more configuration
# Calculated sensors
calculated_sensors:
- name: "Battery Charging Power"
type: "sensor"
state: >-
{% if states('sensor.{PREFIX}_battery_power_raw') | default(0) | float > 0 %}
{{ states('sensor.{PREFIX}_battery_power_raw') | default(0) | float }}
{% else %}
0
{% endif %}
group: "PV_battery_charging"
# Controls
controls:
- name: "Max SOC"
unique_id: "max_soc"
address: 5001
input_type: "holding"
data_type: "uint16"
min_value: 0
max_value: 100All templates support automatic aggregation:
# Aggregate groups with device-specific prefixes
groups:
- "PV_battery_power" # Solar battery power
- "PV_solar_power" # Solar generation
- "PV_grid_power" # Grid interaction
- "EV_charging_power" # EV charging power
- "EV_current_measurement" # EV current monitoring-
Clone Repository:
git clone https://github.com/TCzerny/ha-modbus-manager.git cd ha-modbus-manager -
Copy to Home Assistant:
cp -r custom_components/modbus_manager /path/to/homeassistant/config/custom_components/
-
Restart Home Assistant
-
Add Integration: Configuration → Integrations → Add "Modbus Manager"
custom_components/modbus_manager/
├── __init__.py
├── template_loader.py # Template loader
├── sensor.py # Sensor entities
├── calculated.py # Calculated sensors
├── aggregates.py # Aggregate sensors
├── config_flow.py # Configuration UI
├── device_templates/
│ ├── sungrow_shx.yaml # Sungrow SHx template
│ ├── compleo_ebox_professional.yaml # Compleo eBox template
│ ├── aggregates_hub.yaml # Aggregate sensors template
│ └── base_templates/ # Future SunSpec templates
└── translations/ # UI translations
├── de.json
└── en.json
- Open Home Assistant → Configuration → Integrations
- Click "Add Integration" → "Modbus Manager"
- Select your device template:
- Sungrow SHx Dynamic Inverter for SHx series solar inverters
- Sungrow SG Dynamic Inverter for SG series solar inverters
- Compleo eBox Professional for EV chargers
- Configure connection (Step 1):
- Host: Device IP address
- Port: Modbus port (usually 502)
- Slave ID: Modbus slave address
- Timeout: Connection timeout (default: 5s)
- Delay: Delay between operations (default: 0ms)
- Message Wait: Wait time between requests (default: 100ms)
- Configure device parameters (Step 2):
- Dynamic Templates: Configure phases, MPPT, strings, battery, firmware, connection type
- Model Selection: Select device model for automatic configuration
- Battery Configuration: Choose battery type and slave ID if applicable
- Add another integration → "Modbus Manager"
- Select "Modbus Manager Aggregates"
- Choose aggregate sensors to create
- Configure prefix (e.g., "total" for overall aggregates)
# Lovelace Dashboard Example
type: entities
title: "Energy Overview"
entities:
# Individual devices
- sensor.sg1_battery_level
- sensor.ebox1_charging_power
# Aggregates
- sensor.total_pv_battery_power_sum
- sensor.total_ev_charging_power_sum
- sensor.efficiency_average- File:
sungrow_shx_dynamic.yaml - Devices: All 36 SHx models (SHxK6, SHxK-20/V13, SHxK-30, SHx.0RS, SHx.0RT/RT-20/RT-V112/RT-V122, SHxT, MGxRL)
- Features:
- Multi-Step Configuration: Connection parameters → Dynamic configuration
- Dynamic Configuration: 6 configurable parameters (phases, MPPT, battery, firmware, strings, connection)
- Battery Options: None, Standard Battery, SBR Battery
- Automatic Filtering: Register filtering based on device configuration
- Battery management: SOC, charging/discharging, temperature, health monitoring
- MPPT tracking: 1-3 MPPT trackers with individual power calculations
- String tracking: 0-4 strings with individual monitoring
- Grid interaction: Import/export, phase monitoring, frequency, meter data
- Load management: Load power, backup power, direct consumption
- Calculated sensors: Efficiency, power balance, signed battery power, phase power
- Firmware compatibility: Automatic sensor parameter adjustment for different firmware versions
- Connection support: LAN (full access) and WINET (limited access) with register filtering
- File:
sungrow_sg_dynamic.yaml - Devices: SG3.0RS, SG4.0RS, SG5.0RS, SG6.0RS, SG8.0RS, SG10RS, SG3.0RT, SG4.0RT, SG5.0RT, SG6.0RT
- Features:
- 2-Step Configuration: Connection parameters → Model selection
- Model Selection: Automatic configuration based on selected model
- Automatic Filtering: Phases, MPPT, Strings configured automatically
- Firmware Support: SAPPHIRE-H firmware compatibility
- Connection Types: LAN and WINET support
- MPPT tracking: 2-3 MPPT trackers based on model
- Phase support: 1-phase (RS) and 3-phase (RT) models
- String tracking: 1 string per model
- File:
compleo_ebox_professional.yaml - Devices: Compleo eBox Professional, Innogy eBox
- Features:
- 3-phase charging control
- Current monitoring per phase
- Power calculations
- Fallback current settings
- Cable status monitoring
- Total PV Battery Power: Sum of all battery power
- Total PV Solar Power: Sum of all solar generation
- Total PV Grid Power: Sum of all grid interaction
- Average PV Efficiency: Average efficiency across inverters
- Total EV Charging Power: Sum of all charging power
- Total EV Current: Sum of all charging current
- Active EV Chargers: Count of active chargers
- Average EV Efficiency: Average charging efficiency
- Total Energy System Power: All devices combined
- Device Count: Total number of devices
- System Efficiency: Overall system efficiency
- Aggregate sensors show double counting with multiple devices (expected behavior)
- Fork the repository
- Create device template in
device_templates/ - Add documentation in the GitHub Wiki
- Test with real device
- Create Pull Request
- Use device-specific group prefixes (
PV_,EV_,BAT_, etc.) - Include all relevant sensors and controls
- Add calculated sensors for derived values
- Document register mapping
- Test with real hardware
- GitHub Wiki - Complete documentation
- 📚 Template Documentation - Complete template documentation overview
- Sungrow SHx Dynamic - Complete dynamic template documentation
- Sungrow SHx (Legacy) - Legacy template documentation
- SunSpec Standard Config - Universal SunSpec template
- Compleo eBox Professional - EV charger template
This project is licensed under the MIT License - see the LICENSE file for details.
- Home Assistant Community for the great platform
- Device Manufacturers for Modbus documentation
- Community Contributors for device testing
- mkaiser for the outstanding Sungrow SHx Modbus implementation
- photovoltaikforum.com and forum.iobroker.net communities for reverse-engineering efforts
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Wiki: GitHub Wiki
Last Updated: January 2025 Version: 3.0.0 Status: Stable (Multi-step configuration, Model selection implemented)