Skip to content

Home

Jump to bottom
TCzerny edited this page Sep 3, 2025 · 11 revisions

Modbus Manager Wiki

Welcome to the comprehensive documentation for the Home Assistant Modbus Manager - a beta version, modular, template-based Modbus Manager with predefined device templates for popular energy devices.

Table of Contents

  1. What is Modbus Manager?
  2. 🚀 New in Version 0.5.0
  3. Predefined Templates
  4. 🌍 Internationalization
  5. ⚙️ Dynamic Configuration
  6. 🔢 Float Data Types
  7. 🔧 Services & Diagnostics
  8. Aggregate Sensors
  9. Future Development
  10. Quick Start Guide
  11. Documentation
  12. Use Cases
  13. Known Limitations
  14. Support
  15. License

What is Modbus Manager?

Modbus Manager is a beta version Home Assistant integration that provides ready-to-use templates for popular energy devices. Instead of manually configuring Modbus registers, you simply select a device template and configure the connection.

Key Benefits

  • 🎯 Predefined Templates: No need to manually configure Modbus registers

  • ⚙️ Dynamic Configuration: Automatic sensor filtering based on device parameters

  • 🔢 Float Support: Complete IEEE 754 32-bit and 64-bit floating-point conversion

  • 📊 Aggregate Sensors: Automatic aggregation across multiple devices

  • 🔧 Services & Diagnostics: Built-in optimization and performance monitoring

  • 🔧 Easy Setup: Simple configuration through Home Assistant UI

  • 📈 Scalable: Support for multiple devices with automatic grouping

  • 🔄 Real-time: Live monitoring and control of your energy devices

🚀 New in Version 0.5.0

⚙️ Enhanced Dynamic Configuration

  • Automatic sensor filtering based on device parameters
  • Phase filtering (1/3 phases) with automatic exclusion
  • MPPT filtering (1-3 trackers) with intelligent detection
  • Battery filtering with comprehensive keyword detection
  • Firmware version compatibility with sensor replacements
  • Connection type filtering (LAN/WINET register availability)

🔢 Complete Float Conversion Support

  • IEEE 754 32-bit (float32) floating-point conversion
  • IEEE 754 64-bit (float64) floating-point conversion
  • Automatic count=2 assignment for float32 data types
  • Byte order handling for different endianness
  • Error handling for invalid float values

🔧 Services & Diagnostics

  • modbus_manager_optimize_registers service for register optimization
  • modbus_manager_get_performance service for performance metrics
  • modbus_manager_reset_performance service for metrics reset
  • Comprehensive diagnostics panel via Home Assistant UI
  • Performance monitoring with success rates and operation tracking
  • Register optimization statistics and batch reading analysis

Predefined Templates

Modbus Manager uses predefined templates to simplify device configuration. Each template contains all necessary Modbus register mappings, sensor definitions, and control interfaces for specific devices.

Template Structure

Each device template includes:

  • 📊 Raw Modbus Sensors: Direct register readings from the device
  • 🧮 Calculated Sensors: Derived values and calculations (efficiency, power balance, etc.)
  • 🎛️ Controls: Device control interfaces (settings, modes, limits)
  • 🔍 Binary Sensors: Status indicators and alarms
  • 📈 Aggregate Integration: Automatic grouping for multi-device setups
  • 🏷️ Device Grouping: Organized sensor groups with consistent prefixes

Device-Specific Grouping

All sensors are organized into device-specific groups:

  • PV_ prefix for solar devices (Sungrow)
  • EV_ prefix for EV chargers (Compleo)
  • BAT_ prefix for battery systems (future)
  • GRID_ prefix for grid devices (future)

Sungrow SHx Series Example

The Sungrow SHx Series template provides comprehensive support for Sungrow hybrid inverters:

  • Device Models: SH5K, SH10K, SH15K, SH20K
  • Features: Battery management, MPPT tracking, grid interaction, load management
  • Sensors: 50+ sensors including battery SOC, solar generation, grid interaction
  • Controls: Battery settings, grid limits, system modes
  • Groups: PV_battery_power, PV_mppt_power, PV_grid_power, PV_load_power
  • Dynamic Configuration: Phase filtering, MPPT count detection, battery support

Compleo eBox Professional Example

The Compleo eBox Professional template provides complete EV charger support:

  • Device Models: Compleo eBox Professional, Innogy eBox
  • Features: 3-phase charging control, current monitoring, fallback settings
  • Sensors: Charging power, current per phase, efficiency calculations
  • Controls: Current settings, fallback current, charging control
  • Groups: EV_charging_power, EV_current, EV_efficiency

⚙️ Dynamic Configuration

Automatic Sensor Filtering

The system automatically filters sensors based on device parameters:

Phase Filtering

  • 1 Phase: Excludes 3-phase specific sensors
  • 3 Phase: Includes all phase-related sensors
  • Automatic detection from device parameters

MPPT Filtering

  • 1-3 Trackers: Filters MPPT sensors based on count
  • Intelligent detection of available trackers
  • Automatic sensor exclusion for unavailable trackers

Battery Filtering

  • Comprehensive keyword detection for battery support
  • Automatic sensor inclusion/exclusion based on battery capability
  • Firmware version compatibility checks

Connection Type Filtering

  • LAN vs WINET: Different register availability
  • Automatic sensor filtering based on connection type
  • Register availability detection

Configuration Example

# Sungrow SHx Dynamic Configuration
prefix: "sungrow_inverter"
phases: 3                    # 1 or 3 phases
mppt_count: 2                # 1-3 MPPT trackers
battery_enabled: true        # Battery support
firmware_version: "SAPPHIRE-H_03011.95.01"
connection_type: "LAN"       # LAN or WINET

🔢 Float Data Types

Supported Formats

  • IEEE 754 32-bit (float32) - 4 bytes, count=2
  • IEEE 754 64-bit (float64) - 8 bytes, count=4
  • Automatic byte order handling for different endianness

Configuration Example

# Example float sensor configuration
- name: "Battery Current"
  unique_id: "battery_current"
  address: 5000
  data_type: "float32"      # 32-bit IEEE 754
  count: 2                   # Auto-assigned
  scale: 0.1
  precision: 2

Error Handling

  • Invalid float values are handled gracefully
  • Conversion errors are logged for debugging
  • Fallback values provided when conversion fails

🔧 Services & Diagnostics

Available Services

Register Optimization

service: modbus_manager_optimize_registers
data:
  device_id: "your_device_id"

Performance Monitoring

service: modbus_manager_get_performance
data:
  device_id: "your_device_id"

Reset Performance Metrics

service: modbus_manager_reset_performance
data:
  device_id: "your_device_id"

Diagnostics Panel

  • Comprehensive performance metrics
  • Success rates and operation tracking
  • Register optimization statistics
  • Batch reading analysis
  • Real-time monitoring data

Aggregate Sensors

Aggregate sensors allow you to combine values from multiple Modbus Manager devices and create higher-level statistics. This is particularly useful for solar installations with multiple inverters, battery storage systems, or other energy devices.

What are Aggregate Sensors?

Aggregate sensors collect data from all sensors with the same group property and calculate:

  • Sum: Addition of all values (total power, total current)
  • Average: Arithmetic mean (average efficiency, average temperature)
  • Maximum: Highest value (peak power, maximum temperature)
  • Minimum: Lowest value (minimum voltage, minimum efficiency)
  • Count: Number of devices/sensors (active device count)

How to Use Aggregate Sensors

  1. Create Aggregate Hub: Add "Modbus Manager Aggregates" integration
  2. Select Groups: Choose which sensor groups to aggregate
  3. Configure Methods: Select calculation methods (sum, average, max, min, count)
  4. Set Prefix: Define unique prefix for aggregate sensors

Example Aggregate Setup

# Multiple devices with aggregates
Devices:
  - Sungrow SH10K (prefix: sg1)
  - Sungrow SH15K (prefix: sg2)
  - Compleo eBox (prefix: ebox1)

Aggregates:
  - Total PV Battery Power: sg1 + sg2 battery power
  - Total PV Solar Power: sg1 + sg2 solar power
  - Total EV Charging Power: ebox1 charging power
  - Average Efficiency: (sg1 + sg2 + ebox1) / 3
  - Device Count: Number of active devices

For detailed information, see the Aggregate Sensors Documentation.

Future Development

SunSpec Standard Support

The Modbus Manager is planned to support the SunSpec standard, which will enable support for a wide range of solar inverters and energy devices:

Planned SunSpec Devices

  • SMA - Sunny Boy, Tripower, Home Storage
  • Fronius - GEN24, Tauro
  • Huawei - Luna, FusionSolar
  • SolarEdge - HD Wave, StorEdge

Benefits of SunSpec

  • Standardized Interface: Common register mapping across manufacturers
  • Wider Device Support: Support for hundreds of devices
  • Future-Proof: Industry standard for renewable energy devices
  • Simplified Development: Reduced template development time

Other Planned Standards

Additional Manufacturers

  • Kostal - Piko, Plenticore series
  • Growatt - MIN, MAX series
  • Victron - MultiPlus, Quattro
  • Sofar - Solar inverters and battery systems

Advanced Features

  • Custom Template Editor: GUI for creating custom templates
  • Template Marketplace: Community-shared templates
  • Advanced Analytics: Historical data analysis and reporting
  • Cloud Integration: Optional cloud-based monitoring and control

Quick Start Guide

Installation

  1. Clone Repository:

    git clone https://github.com/TCzerny/ha-modbus-manager.git
cd ha-modbus-manager

  2. Copy to Home Assistant:

    cp -r custom_components/modbus_manager /path/to/homeassistant/config/custom_components/

  3. Restart Home Assistant

  4. Add Integration: Configuration → Integrations → Add "Modbus Manager"

Adding Your First Device

  1. Open Home Assistant → Configuration → Integrations
  2. Click "Add Integration" → "Modbus Manager"
  3. Select your device template:
    • Sungrow SHx Inverter for solar inverters
    • Compleo eBox Professional for EV chargers
  4. Configure connection:
    • Host: Device IP address
    • Port: Modbus port (usually 502)
    • Slave ID: Modbus slave address
    • Prefix: Unique prefix for this device
  5. Configure device parameters:
    • Phases: Number of phases (1 or 3)
    • MPPT Count: Number of MPPT trackers
    • Battery Enabled: Battery support status
    • Firmware Version: Device firmware version
    • Connection Type: LAN or WINET

Adding Aggregate Hub

  1. Add another integration → "Modbus Manager"
  2. Select "Modbus Manager Aggregates"
  3. Choose aggregate sensors to create
  4. Configure prefix (e.g., "total" for overall aggregates)

Documentation

Device Templates

Features

Related Documentation

Use Cases

Home Solar System

  • Monitor solar generation, battery status, grid interaction
  • Control battery charging, export limits, system modes
  • Automate based on solar production, battery levels, grid prices
  • Optimize performance using built-in services

EV Charging

  • Monitor charging power, current, efficiency
  • Control charging current, fallback settings
  • Automate charging based on solar production, time-of-use rates
  • Track performance metrics and optimization

Energy Management

  • Aggregate data from multiple devices
  • Optimize energy flows between solar, battery, grid, loads
  • Monitor overall system efficiency and performance
  • Diagnose issues using comprehensive diagnostics

Known Limitations

  • Device Support: Currently limited to Sungrow and Compleo devices
  • Modbus Only: Only supports Modbus TCP protocol
  • Template-based: Requires predefined templates (no custom register configuration)
  • Home Assistant: Requires Home Assistant 2023.8+
  • Float Support: Limited to IEEE 754 32-bit and 64-bit formats

Support

License

This project is licensed under the MIT License - see the LICENSE file for details.

Last Updated: January 2025
Version: 0.5.0
Status: Beta Version - Ready for Testing
Maintainer: TCzerny

Clone this wiki locally