SolarEdge 2 MQTT Service

The SolarEdge2MQTT service facilitates the retrieval of power data from SolarEdge inverters and its publication to an MQTT broker. Ideal for integrating SolarEdge inverters into home automation systems, this service supports real-time monitoring of power flow and additional parameters via Modbus.

Users can optionally collect panel energy production and power data directly from the SolarEdge monitoring site, without employing the API, by leveraging their monitoring platform account.

🔧 Features

SolarEdge2MQTT provides a comprehensive feature set for power monitoring, home automation integration, and advanced analysis. Key capabilities include:

• 📡 Modbus communication with SolarEdge inverters (via TCP/IP)
• 🧠 Leader/follower support for multi-inverter cascaded setups
• ⚡ Power flow monitoring, including:
  • Inverter production
  • Battery status and charge/discharge
  • Grid import/export
  • Consumption and generation via Modbus meters
• 🕸️ MQTT integration for use with Home Assistant and other systems
• 🔄 Home Assistant auto discovery support (optional)
• 📈 PV production forecasting using a built-in machine learning model
  → uses live weather data from OpenWeatherMap and historical data from InfluxDB
• 💡 Data logging to InfluxDB (raw and aggregated values)
• 💸 Price-based savings calculation for consumption and export
• 🔌 SolarEdge Wallbox monitoring via REST API
• 🌐 Module-level monitoring by retrieving data directly from the SolarEdge monitoring site (no API key needed)
• 🚗 EV charger monitoring and control via SolarEdge monitoring account — status, session energy, and remote charge level control
• 🐳 Docker and Docker Compose support for easy deployment
• 🧪 Console mode for development and testing

It also enables the monitoring of SolarEdge Wallbox via the REST API and supports saving all values into InfluxDB for advanced visualization.

Contact and Feedback

For inquiries, feel free to reach out on Discord.

We highly value your input. Share your ideas, suggestions, or issues by opening an issue. Your feedback is eagerly awaited.

Support

If you like this project, I would appreciate a small contribution.

Configuration

SolarEdge2MQTT uses YAML-based configuration files for easy and structured setup. Configuration is stored in two files:

• configuration.yml: Contains all non-sensitive settings
• secrets.yml: Contains sensitive data (passwords, tokens, API keys)

Quick Start

For new installations, the service will automatically create example configuration files on first run if they don't exist. Simply start the service and it will guide you through the setup process.

Configuration Files

You can download example configuration files to get started:

• configuration.yml.example
• secrets.yml.example

Setup steps:

1. Create a config/ directory (or use --config-dir to specify a different location)
2. Copy the example files and rename them to configuration.yml and secrets.yml
3. Edit both files with your specific settings

Configurable Configuration Directory

By default, SolarEdge2MQTT looks for configuration files in the config/ directory. You can specify a different location using the --config-dir argument:

# Use default config directory (./config/)
solaredge2mqtt

# Use custom config directory
solaredge2mqtt --config-dir /etc/solaredge2mqtt

# Show help
solaredge2mqtt --help

Migration from Environment Variables

⚠️ Breaking Change: Starting with version 2.3.0, SolarEdge2MQTT uses YAML configuration files instead of environment variables.

If you're upgrading from a previous version that used environment variables, .env files, or Docker secrets, SolarEdge2MQTT provides automatic and manual migration paths.

📖 For detailed migration instructions, see the Migration Guide

The migration guide covers:

• ✅ Automatic migration on first startup
• ✅ Manual migration with the CLI tool
• ✅ Docker-specific migration procedures
• ✅ Environment variable to YAML mapping
• ✅ Post-migration verification
• ✅ Troubleshooting common issues

Quick Migration Overview:

When you start the service after upgrading, it will automatically:

1. Detect existing environment variables from .env files, environment, or Docker secrets
2. Create configuration.yml and secrets.yml in your config directory
3. Separate sensitive values into secrets.yml with secure permissions
4. Start normally with your migrated configuration

For more control, use the migration tool:

solaredge2mqtt-migrate --input .env --output-dir config --backup

→ Read the full Migration Guide

Secret References

To keep sensitive data secure, use the !secret tag in your configuration. This tag references values stored in secrets.yml:

# configuration.yml
mqtt:
  broker: mqtt.example.com
  password: !secret mqtt_password

# secrets.yml
mqtt_password: "your_actual_password"

Benefits of using secrets.yml:

• Sensitive data is separated from main configuration
• secrets.yml is automatically created with restrictive 600 permissions
• Easy to exclude from version control
• Can be managed separately in deployment pipelines

The migration tool automatically identifies sensitive fields (passwords, tokens, API keys, serial numbers, site IDs) and moves them to secrets.yml.

The available configuration options are listed below:

Basic configuration

# Interval between data retrieval requests (in seconds)
interval: 5

# Logging verbosity: DEBUG, INFO, WARNING, ERROR, or CRITICAL
logging_level: INFO

# Location for weather and forecast services
location:
  latitude: 52.520008
  longitude: 13.404954

# Set to true if you have additional producers
powerflow:
  external_production: false

# Optional status debounce per service (consecutive checks required before state switch)
modbus:
  debounce_cycles: 2

# wallbox:
#   debounce_cycles: 2

# monitoring:
#   debounce_cycles: 2

# weather:
#   debounce_cycles: 2

# influxdb:
#   debounce_cycles: 2

Basic Modbus configuration

modbus:
  host: 192.168.1.100  # IP address of your SolarEdge inverter
  port: 1502           # Modbus port (default: 1502)
  timeout: 1           # Connection timeout in seconds
  unit: 1              # Unit address (default: 1)
  
  # Enable or disable meter detection (default: true)
  meter:
    - true  # meter0
    - false  # meter1
    - false  # meter2
  
  # Enable or disable battery detection (default: true)
  battery:
    - true  # battery0
    - true  # battery1
  
  # Check grid status (requires extra hardware)
  check_grid_status: false

  # Startup device detection retry (retries indefinitely, never gives up)
  startup_retry_delay: 30       # Initial delay between retries in seconds (default: 30)
  startup_retry_max_delay: 300  # Delay doubles after each retry, capped here (default: 300)

If the inverter is unreachable during startup device detection (e.g. a brief Modbus outage), the service retries with exponential backoff instead of crashing — the delay starts at startup_retry_delay and doubles on each attempt up to startup_retry_max_delay.

Leader/follower setup

SolarEdge inverters support a cascading setup, where one inverter acts as the leader and up to ten others act as followers.

• For the leader inverter, use the basic Modbus settings described above.
• For each follower inverter, add them to the configuration as shown below.

Cascaded inverters (shared Modbus connection)

When followers are wired in a RS485 cascade behind the leader, they share the leader's TCP connection. Only set unit (the Modbus device address on the bus) and optionally meter/battery flags:

modbus:
  host: 192.168.1.100
  port: 1502
  
  follower:
    - unit: 2
      meter: [false, false, false]
      battery: [false, false]
    - unit: 3
      meter: [true, false, false]
      battery: [true, false]

Physically separate inverters (individual TCP connections)

When each inverter has its own network connection (e.g. each has its own IP address), specify host and optionally port per follower. Each follower with its own host opens a dedicated TCP connection; those without fall back to the leader's connection:

modbus:
  # Leader
  host: 192.168.1.100
  port: 1502

  follower:
    # Follower on the same host (cascaded, shares leader connection)
    - unit: 2
      meter: [false, false, false]
      battery: [false, false]

    # Follower with its own IP and default port (1502 inherited from leader)
    - unit: 1
      host: 192.168.1.101
      meter: [true, false, false]
      battery: [true, false]

    # Follower with its own IP and a custom port
    - unit: 1
      host: 192.168.1.102
      port: 502
      meter: [false, false, false]
      battery: [true, true]

When a follower omits port, the leader's port is used. When a follower omits host, the leader's host and connection are reused.

You can configure up to 11 inverters in total: one leader and up to 10 followers. Each configured inverter will report:

• individual power flow data
• individual energy data (if enabled)
• cumulative energy and power flow data
• cumulative production forecasts (if forecasting is enabled)

This setup allows for comprehensive multi-inverter support in systems with cascaded or physically separate SolarEdge installations.

MQTT configuration

mqtt:
  client_id: solaredge2mqtt        # MQTT client identifier
  broker: mqtt.example.com         # IP address of MQTT broker
  port: 1883                       # MQTT port (default: 1883)
  username: mqtt_user              # MQTT username
  password: !secret mqtt_password  # Use !secret to reference secrets.yml
  topic_prefix: solaredge          # MQTT topic prefix
  use_tls: false                   # Enable TLS encryption (default: false)
  ca_certs: /path/to/ca.pem        # Path to CA certificate bundle
  certfile: /path/to/client.pem    # Client certificate for mutual TLS
  keyfile: /path/to/client.key     # Private key matching certfile
  keyfile_password: !secret mqtt_keyfile_password  # Only if the private key is encrypted
  tls_verify: true                 # Verify TLS certificates (default: true)

If your broker authenticates clients by certificate instead of (or in addition to) a password, set certfile and keyfile to the client keypair. They are only used when use_tls is enabled, and keyfile_password is needed only when the private key itself is encrypted. All three are unset by default.

Note: Store your password securely in secrets.yml:

# secrets.yml
mqtt_password: "your_actual_password"
mqtt_keyfile_password: "your_actual_key_password"

The service also publishes operational topics below the configured topic_prefix:

• status/<service> for subservice connection states (online/offline) such as modbus, wallbox, monitoring, influxdb, and weather_api
• logging for runtime log messages (MQTT warnings/errors are excluded from MQTT log forwarding)

Use the debounce_cycles field within each service's configuration to reduce status flapping by requiring repeated online/offline observations before a state change is published.

Retain Configuration

By default, MQTT messages are not retained. You can configure the retain flag for each message type:

energy:
  retain: false

forecast:
  retain: false

homeassistant:
  retain: false

monitoring:
  retain: false

powerflow:
  retain: false

wallbox:
  retain: false

weather:
  retain: false

Monitoring

To enable panel energy and power value retrieval from the SolarEdge monitoring platform:

monitoring:
  site_id: !secret monitoring_site_id     # Your SolarEdge site ID (store in secrets.yml)
  username: "user@example.com"             # SolarEdge platform username
  password: !secret monitoring_password    # Store in secrets.yml
  retain: false

Remember to add the site_id and password to secrets.yml:

# secrets.yml
monitoring_site_id: "12345678"
monitoring_password: "your_monitoring_password"

EV Charger monitoring and control

If EV chargers are registered in your SolarEdge monitoring account, they are automatically discovered on startup — no additional configuration is needed beyond the standard monitoring credentials above.

Status is polled on every base interval and published to MQTT under:

monitoring/evcharger/{reporter_id}

The payload includes:

Charge level control

To set the charge level remotely, publish to:

monitoring/evcharger/{reporter_id}/charge_level

with a JSON payload:

{"level": 100}

level must be an integer 0 for off or 100 for on. Other values are not possible at the moment. The service translates this into a MANUAL mode command sent to the SolarEdge monitoring API.

When Home Assistant auto discovery is enabled, the following entities are created automatically per charger:

• A number entity for charge level control
• A sensor for charger status
• A binary sensor for vehicle connection (plug)
• Sensors for session energy and rated power

Wallbox

For monitoring SolarEdge Wallbox:

wallbox:
  host: 192.168.1.101                     # Wallbox IP address
  password: !secret wallbox_password      # Admin password (store in secrets.yml)
  serial: !secret wallbox_serial          # Wallbox serial number (store in secrets.yml)
  retain: false

Add the password and serial to secrets.yml:

# secrets.yml
wallbox_password: "your_wallbox_admin_password"
wallbox_serial: "ABC123456"

Home Assistant Auto Discovery

Enable Home Assistant auto discovery:

homeassistant:
  enable: true                 # Enable auto discovery
  topic_prefix: homeassistant  # MQTT discovery topic prefix
  retain: false

To remove entities, disable the feature, restart SolarEdge2MQTT first, then restart Home Assistant.

InfluxDB

Configure InfluxDB for data storage:

influxdb:
  host: http://localhost           # InfluxDB host
  port: 8086                       # InfluxDB port (default: 8086)
  token: !secret influxdb_token    # Access token (store in secrets.yml)
  org: my_org                      # Organization ID
  bucket: solaredge                # Bucket name (default: solaredge)
  retention_raw: 25                # Raw data retention in hours
  retention: 63072000              # Aggregated data retention in seconds (2 years)

Add the token to secrets.yml:

# secrets.yml
influxdb_token: "your_influxdb_token_with_full_access"

Note: The token requires full access as the service manages buckets and tasks.

Price Configuration

Calculate savings and earnings by specifying energy costs. Requires InfluxDB.

prices:
  consumption: 0.30  # Price paid per kWh from grid
  delivery: 0.08     # Price received per kWh delivered to grid

Weather

Integrate real-time weather data from OpenWeatherMap:

weather:
  api_key: !secret weather_api_key  # OpenWeatherMap API key (store in secrets.yml)
  language: en                       # Language for weather data (default: en)
  retain: false

Add the API key to secrets.yml:

# secrets.yml
weather_api_key: "your_openweathermap_api_key"

To access weather data, you need an OpenWeatherMap account, an API key, and a subscription to the One-Call API. Visit OpenWeatherMap for more information.

Forecast

The service features machine learning-based PV production forecasting. Requires location, InfluxDB, and weather configuration.

forecast:
  enable: false                      # Enable forecasting (default: false)
  hyperparametertuning: false        # Enable hyperparameter tuning (CPU intensive)
  cachingdir: ~/.cache/se2mqtt_forecast  # Cache directory for pipeline results
  retain: false

Prerequisites:

• Minimum 60 hours of training data must be collected before forecasting begins
• Data recording must be consistent (gaps longer than an hour prevent training data collection)

Note: Forecast service is not available for arm/v7 architectures due to dependency compatibility issues.

Tip:

Want to use SolarEdge2MQTT forecasts in the Home Assistant Energy Dashboard?

Install the companion integration:

SolarEdge2MQTT Forecast https://github.com/DerOetzi/solaredge2mqtt_forecast

It consumes forecast data published by SolarEdge2MQTT via MQTT and makes it available as a solar forecast provider in Home Assistant.

Running the service

Each method provides different levels of control and isolation, suitable for various use cases from development to production deployment.

In the Console

For development and testing environments:

1. Preparation: Ensure Python >=3.11, <=3.13 is installed.

2. Installation:

   pip install -U solaredge2mqtt
   

   For forecast functionality:

   pip install -U solaredge2mqtt[forecast]
   

3. Configuration:

   • Create a config/ directory (or use a custom location with --config-dir)
   • Download configuration.yml.example and save as config/configuration.yml
   • Download secrets.yml.example and save as config/secrets.yml
   • Edit both files with your specific settings

4. Execution:

   # Use default config directory (./config/)
   solaredge2mqtt
   
   # Use custom config directory
   solaredge2mqtt --config-dir /path/to/config
   

New Installation Flow: On first run without configuration files, the service will automatically copy example files to your config directory and exit with instructions. Edit the files and run again.

Migration from older versions: If you have an existing .env file, the service will automatically create YAML configuration files in the config/ directory on first run. See the Migration section for details.

Docker Deployment

For Docker and Docker Compose deployment instructions, see the Docker Deployment Guide.

The Docker deployment guide covers:

• Running with Docker
• Running with Docker Compose
• Automatic permission handling
• Migration from environment variables
• Troubleshooting

Troubleshooting

Invalid Register Data / UnicodeDecodeError on Meter Detection

Symptom: You see error messages like:

ERROR: Skipping meter2 due to invalid register data in device info
ERROR: Failed to decode register 'c_manufacturer' at address 40123: 'utf-8' codec can't decode byte...

Cause: This typically occurs when:

• A meter position is configured but no physical meter is installed
• The meter is reporting uninitialized or corrupted data
• There is a communication issue with the meter

Solution:

If you do not have a meter installed at this position (e.g., meter2), you can disable its detection in your configuration:

1. Open config/configuration.yml
2. Find the modbus section
3. Set the corresponding meter array element to false:

modbus:
  # ... other settings ...
  meter:
    - true   # meter0 (index 0)
    - false  # meter1 (index 1) - disable if not installed
    - false  # meter2 (index 2) - disable if not installed

4. Restart the service

If you do have a meter installed at this position:

• Check the physical connection between the inverter and meter
• Verify the meter is powered and functioning
• Check inverter logs for communication errors
• Consider contacting SolarEdge support if the issue persists

Note: The service will continue to operate and monitor other devices even when a meter fails to respond. Only the problematic meter will be skipped.

Installation Examples

This section provides practical examples for different deployment scenarios, from simple console installations to complete Docker-based stacks.

Console Installation Examples

Example 1: Basic Console Installation

Minimal setup for testing or development without forecast support:

# Install the package
pip install -U solaredge2mqtt

# Create and configure
mkdir -p config
curl -o config/configuration.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/configuration.yml.example
curl -o config/secrets.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/secrets.yml.example

# Protect secrets file (recommended: only readable by owner)
chmod 600 config/secrets.yml
# Edit configuration files with your settings
nano config/configuration.yml
nano config/secrets.yml

# Run the service
solaredge2mqtt

Example 2: Console Installation with Forecast Support

Complete installation including machine learning forecast capabilities:

# Install with forecast support
pip install -U solaredge2mqtt[forecast]

# Create and configure
mkdir -p config
curl -o config/configuration.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/configuration.yml.example
curl -o config/secrets.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/secrets.yml.example

# Protect secrets file (recommended: only readable by owner)
chmod 600 config/secrets.yml

# Edit configuration files
# Enable forecast in configuration.yml:
#   forecast:
#     enable: true
nano config/configuration.yml
nano config/secrets.yml

# Run the service
solaredge2mqtt

Example 3: Console with Custom Config Directory

Using a system-wide configuration directory:

# Install the package
pip install -U solaredge2mqtt

# Create custom config directory
sudo mkdir -p /etc/solaredge2mqtt
sudo curl -o /etc/solaredge2mqtt/configuration.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/configuration.yml.example
sudo curl -o /etc/solaredge2mqtt/secrets.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/secrets.yml.example

# Edit configuration files
sudo nano /etc/solaredge2mqtt/configuration.yml
sudo nano /etc/solaredge2mqtt/secrets.yml

# Run with custom config directory
solaredge2mqtt --config-dir /etc/solaredge2mqtt

Docker Installation Examples

Example 4: Basic Docker Installation

Simple Docker deployment with persistent configuration:

# Create config directory
mkdir -p config

# Download configuration examples
curl -o config/configuration.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/configuration.yml.example
curl -o config/secrets.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/secrets.yml.example

# Protect secrets file (recommended: only readable by owner)
chmod 600 config/secrets.yml

# Edit configuration files
nano config/configuration.yml
nano config/secrets.yml

# Run the container
docker run -d --name solaredge2mqtt \
    -v $(pwd)/config:/app/config \
    -e "TZ=Europe/Berlin" \
    --restart unless-stopped \
    ghcr.io/deroetzi/solaredge2mqtt:latest

# View logs
docker logs solaredge2mqtt -f

Example 5: Basic Docker Compose

Minimal docker-compose.yml for standalone deployment:

services:
  solaredge2mqtt:
    container_name: solaredge2mqtt
    image: ghcr.io/deroetzi/solaredge2mqtt:latest
    volumes:
      - ./config:/app/config
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

Setup and run:

# Download the compose file
curl -o docker-compose.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/docker-compose.yml

# Prepare configuration
mkdir -p config
curl -o config/configuration.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/configuration.yml.example
curl -o config/secrets.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/secrets.yml.example

# Protect secrets file (recommended: only readable by owner)
chmod 600 config/secrets.yml

# Edit configuration
nano config/configuration.yml
nano config/secrets.yml

# Start the service
docker compose up -d

# View logs
docker compose logs solaredge2mqtt -f

Example 6: Full-Stack Docker Compose with InfluxDB and Grafana

Complete monitoring and visualization stack:

services:
  solaredge2mqtt:
    container_name: solaredge2mqtt
    image: ghcr.io/deroetzi/solaredge2mqtt:latest
    volumes:
      - ./config:/app/config
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

  influxdb:
    image: influxdb:latest
    container_name: influxdb
    ports:
      - "8086:8086"
    volumes:
      - "./data:/var/lib/influxdb2"
    restart: always

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - "grafana:/var/lib/grafana"
    restart: always

volumes:
  grafana:

For the complete full-stack example with advanced features, see examples/docker-compose-full-stack.yaml

Systemd Service Example (Linux)

Example 7: Running as a System Service

Create a systemd service for automatic startup on Linux systems:

Create service file /etc/systemd/system/solaredge2mqtt.service:

[Unit]
Description=SolarEdge 2 MQTT Service
After=network.target

[Service]
Type=simple
User=yourusername
WorkingDirectory=/etc/solaredge2mqtt
ExecStart=/usr/local/bin/solaredge2mqtt --config-dir /etc/solaredge2mqtt
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Setup and enable:

# Install the service
pip install -U solaredge2mqtt

# Prepare configuration
sudo mkdir -p /etc/solaredge2mqtt
sudo curl -o /etc/solaredge2mqtt/configuration.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/configuration.yml.example
sudo curl -o /etc/solaredge2mqtt/secrets.yml https://raw.githubusercontent.com/DerOetzi/solaredge2mqtt/master/solaredge2mqtt/config/secrets.yml.example
# Restrict access to secrets file (contains sensitive credentials)
sudo chmod 600 /etc/solaredge2mqtt/secrets.yml
sudo nano /etc/solaredge2mqtt/configuration.yml
sudo nano /etc/solaredge2mqtt/secrets.yml

# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable solaredge2mqtt
sudo systemctl start solaredge2mqtt

# Check status and logs
sudo systemctl status solaredge2mqtt
sudo journalctl -u solaredge2mqtt -f

Migration Example

Example 8: Migrating from Environment Variables

If you're upgrading from an older version using environment variables:

# Your old .env file will be automatically detected
# Run the service once to migrate
solaredge2mqtt

# The service creates configuration.yml and secrets.yml in config/
# Review the migrated files
cat config/configuration.yml
cat config/secrets.yml

# Make any necessary adjustments
nano config/configuration.yml

# Restart the service (now using YAML configuration)
solaredge2mqtt

For Docker migrations, see the Docker Deployment Guide.

Quick Start Examples by Use Case

Just want to monitor my inverter?
→ Use Example 1 or Example 4

Need production forecasting?
→ Use Example 2 (requires InfluxDB and weather configuration)

Want historical data and dashboards?
→ Use Example 6

Running on a server permanently?
→ Use Example 7 (systemd) or Example 5 (Docker)