Chisage Inverter Modbus Configuration Generator for Home Assistant

Version: 0.1.0
Author: Rouven Raudzus (Autiwire GmbH)
Email: raudzus@autiwire.de
Copyright: 2025 Autiwire GmbH
License: Apache License 2.0 (License URL)

Thanks to Chisage Company for their support and high quality modbus documentation.

Overview

This Python script (chisage-generate.py) automates the creation of Modbus configuration YAML files for Chisage inverters, tailored for integration with Home Assistant. It can generate configurations for multiple inverters, assign IP addresses and ports incrementally or fixed, and optionally create basic Lovelace UI card configurations.

The script produces:

1. A main modbus_devices.yaml file, which lists all configured Modbus hubs (inverters). This file is intended to be included in your Home Assistant configuration.yaml.
2. Individual sensor definition files for each inverter (e.g., chisage/chisage_1_sensors.yaml), which are included by modbus_devices.yaml.
3. Optional Lovelace UI card definition files for each inverter (e.g., chisage/chisage_1_card.yaml).

Targets

• Chisage Mars-5-14G2-LE with current firmware

Features

• Generates Home Assistant Modbus TCP hub configurations.
• Defines a list of Modbus sensors for Chisage inverters based on a predefined register map.
• Supports configuration for multiple inverters.
• Flexible IP address assignment:
  • Incremental (last octet increases from a starting IP).
  • Fixed (all inverters use the same IP).
• Flexible Port assignment:
  • Incremental (port number increases from a starting port).
  • Fixed (all inverters use the same port).
• Optional generation of basic Lovelace UI entities card configurations for each inverter.
• Organizes generated files into a chisage subdirectory.

Requirements

• Python 3.6+
• PyYAML library (pip install pyyaml)

Usage

The script is controlled via command-line arguments:

python chisage-generate.py --count <num_inverters> [ip_options] [port_options] [--slave-id <id>] [--generate-cards]

Arguments:

• --count <number>: (Required) Number of inverters to generate configurations for.
• --slave-id <id>: (Optional) Modbus slave ID to use for all inverters. Defaults to 1.

IP Address Options (Choose one, Required):

• --ip-start <ip_address>: Starting IP address for incremental assignment (e.g., 192.168.1.10). The last octet will be incremented for each subsequent inverter.
• --ip-fixed <ip_address>: Fixed IP address to be used for ALL inverters (e.g., 192.168.1.100).

Port Number Options (Choose one, Required):

• --port-start <port_number>: Starting port number for incremental assignment (e.g., 5001). Will be incremented by 1 for each subsequent inverter.
• --port-fixed <port_number>: Fixed port number to be used for ALL inverters (e.g., 5000).

Card Generation Option:

• --generate-cards: (Optional) If this flag is present, the script will generate Lovelace card YAML configuration files for each inverter (e.g., chisage/chisage_1_card.yaml).

Examples:

1. Generate configuration for 3 inverters with incrementing IPs and ports:

   python chisage-generate.py --count 3 --ip-start 192.168.178.209 --port-start 5001

   • Chisage 1: IP 192.168.178.209, Port 5001
   • Chisage 2: IP 192.168.178.210, Port 5002
   • Chisage 3: IP 192.168.178.211, Port 5003

2. Generate for 2 inverters with a fixed IP, incrementing port, specific slave ID, and generate UI cards:

   python chisage-generate.py --count 2 --ip-fixed 10.0.0.50 --port-start 7000 --slave-id 2 --generate-cards

   • Chisage 1: IP 10.0.0.50, Port 7000, Slave ID 2
   • Chisage 2: IP 10.0.0.50, Port 7001, Slave ID 2

Generated Files Structure

Running the script will create/update the following:

your_home_assistant_config_directory/
|-- configuration.yaml
|-- modbus_devices.yaml         <-- Main Modbus hub list generated by script
|-- chisage-generate.py         <-- This script
|-- chisage/                    <-- Subdirectory for inverter-specific files
    |-- chisage_1_sensors.yaml  <-- Sensor definitions for Inverter 1
    |-- chisage_1_card.yaml     <-- Optional UI card for Inverter 1
    |-- chisage_2_sensors.yaml
    |-- chisage_2_card.yaml
    |-- ... etc.

Home Assistant Integration

Important Note on Chisage Inverter Wiring: For proper Modbus communication and access to all registers, ensure you are using pins 7 and 8 for Modbus data (A/B). Pins 4 and 5 on some Chisage inverters may be a debug port with limited register access and should generally not be used for Home Assistant integration.

1. Include Modbus Hubs: Ensure your main Home Assistant configuration.yaml includes the generated modbus_devices.yaml file under the modbus: integration key:

   # configuration.yaml
   modbus: !include modbus_devices.yaml
   
   # ... other Home Assistant configurations ...

2. Sensor Definitions: The modbus_devices.yaml file will, in turn, include the sensor definitions from the chisage/chisage_X_sensors.yaml files. The script currently defines a range of sensors based on the provided Modbus protocol data for registers 26-62 and 2026-2039. You can customize the sensors by editing the ChisageInverter class within chisage-generate.py.

3. Lovelace UI Cards (if generated): If you used the --generate-cards option, YAML files like chisage/chisage_1_card.yaml will be created. These define a simple entities card. You can add these to your Lovelace UI by:

   • Editing your dashboard in UI mode and adding a "Manual Card".
   • Pasting the content of the _card.yaml file into the card configuration.
   • Alternatively, if you manage your Lovelace configuration in YAML mode, you can use !include directives to add these cards to your views. Example:

     # ui-lovelace.yaml or a view file
     # ...
     cards:
       - !include ../chisage/chisage_1_card.yaml
       - !include ../chisage/chisage_2_card.yaml
     # ...

     Note: The path for !include in Lovelace YAML mode is relative to your Home Assistant configuration directory (where configuration.yaml resides), not necessarily the directory where ui-lovelace.yaml might be if it's split out. Adjust paths as needed.

4. Check Configuration and Restart Home Assistant: After running the script and ensuring your configuration.yaml is set up to include modbus_devices.yaml:

   • Crucial Step: Before restarting Home Assistant, always go to Developer Tools > YAML > Check Configuration in the Home Assistant UI. This will validate your overall configuration, including the newly generated Modbus settings. Fixing any reported errors here can prevent Home Assistant from failing to start.
   • Once the configuration check passes, restart Home Assistant to apply the Modbus configuration changes.

Customization

• Sensor List: To add, remove, or modify the Modbus sensors being generated, edit the inverter_sensors list within the ChisageInverter class in chisage-generate.py. You'll need the Modbus register address, data type, scale factor, and unit of measurement.
• Default Scan Interval: The default_sensor_scan_interval for sensors within the ChisageInverter class can be modified if needed. Some sensors might have explicitly overridden scan intervals.

Troubleshooting

• "Could not determine a constructor for the tag '!include'" in script output: This error during script execution while reading an existing modbus_devices.yaml is now handled by a custom loader in the script. The script should proceed and regenerate the file correctly.
• Home Assistant Configuration Errors (Post-Restart): If Home Assistant still reports errors related to Modbus after a restart (and after a successful configuration check):
  • Double-check that modbus_devices.yaml and the chisage/ subdirectory are in the same directory as your main configuration.yaml.
  • Verify the !include path in your configuration.yaml.
  • Examine the contents of modbus_devices.yaml and one of the chisage_X_sensors.yaml files to ensure they look like valid YAML and that the !include directives are unquoted.
  • Check the Home Assistant logs for more specific error messages.
• Entities Unavailable in UI Card: If sensors appear as "unavailable" in the generated Lovelace cards, ensure that the corresponding ModbusRegister definitions exist in the ChisageInverter class within chisage-generate.py and that Home Assistant has successfully connected to the Modbus TCP device.

---