SolArk Cloud Integration for Home Assistant

A Home Assistant custom integration for Sol-Ark inverter systems that connects to the SolArk Cloud API. Monitor your solar system with real-time data and track long-term energy production with full Energy Dashboard support.

🌟 Key Features

Energy Dashboard Compatible - Native support for Home Assistant's Energy dashboard
Real-time Monitoring - Live power flow tracking (PV, Battery, Grid, Load)
Cloud-based - Connects to solarkcloud.com (auto-discovers API host), no physical connections required
Microinverter-aware PV - Includes portal minPower when micro/AC-coupled PV is present
18 Comprehensive Sensors - All critical solar system metrics
Beautiful Dashboards - Pre-built power flow visualizations
Long-term Statistics - Automatic energy tracking and historical data
Easy Setup - Simple configuration through Home Assistant UI

📊 Sensors Provided

Entity ID	Description	Unit	Energy Dashboard
`sensor.solark_pv_power`	Solar PV power (`pvPower` + `minPower` when present)	W	Power only
`sensor.solark_battery_power`	Battery power (+ discharge, − charge)	W	Power only
`sensor.solark_battery_charge_power`	Battery charge power	W	Power only
`sensor.solark_battery_discharge_power`	Battery discharge power	W	Power only
`sensor.solark_battery_soc`	Battery state of charge	%	Battery level
`sensor.solark_grid_power`	Net grid power	W	Power only
`sensor.solark_load_power`	Home consumption	W	Power only
`sensor.solark_grid_import_power`	Grid import (meter or flow `gridTo`)	W	Power only
`sensor.solark_grid_export_power`	Grid export (meter or flow `toGrid`)	W	Power only
`sensor.solark_grid_import_energy`	Grid import energy	kWh	✅ Direct use
`sensor.solark_grid_export_energy`	Grid export energy	kWh	✅ Direct use
`sensor.solark_battery_charge_energy`	Battery charge energy	kWh	✅ Direct use
`sensor.solark_battery_discharge_energy`	Battery discharge energy	kWh	✅ Direct use
`sensor.solark_home_consumption_energy`	Home consumption energy	kWh	✅ Direct use
`sensor.solark_grid_status`	Grid status	-	Status
`sensor.solark_generator_status`	Generator status	-	Status
`sensor.solark_ac_relay_status`	AC relay status (grid connection)	-	Status
`sensor.solark_energy_today`	Daily production (summed across plant inverters)	kWh	✅ Direct use
`sensor.solark_energy_total`	Lifetime production (summed across plant inverters)	kWh	✅ Solar production

Notes:

Battery power: positive = discharging, negative = charging (from SolArk flow batTo / toBat flags).
PV power includes microinverter / AC-coupled contribution from flow minPower when existsMin / microOn is set (common when string pvPower alone is 0).
Grid import/export use external meter phases when available; otherwise they follow gridOrMeterPower with direction flags.

📋 Requirements

Home Assistant 2024.3.0 or newer
Sol-Ark inverter (12K, 15K, 8K, 5K models)
Active Sol-Ark Cloud account
Your Plant ID from Sol-Ark portal

🚀 Installation

Via HACS (Recommended)

Open HACS → Integrations
Click ⋮ → Custom repositories
Add: https://github.com/HammondAutomationHub/HomeAssistant_SolArk
Category: Integration
Find "SolArk Cloud" and click Download
Restart Home Assistant

Manual Installation

Download latest release
Copy custom_components/solark to your /config/custom_components/ directory
Restart Home Assistant

⚙️ Configuration

1. Get Your Plant ID

Log into solarkcloud.com (mysolark.com still redirects here)
Navigate to your system
Check the URL: https://www.solarkcloud.com/plants/overview/12345/...
Your Plant ID is 12345

2. Add Integration

Settings → Devices & Services → + ADD INTEGRATION
Search "SolArk Cloud"
Enter:
- Username: Your Sol-Ark email
- Password: Your Sol-Ark password
- Plant ID: From step 1
- Auto-discover API URL from portal: on (recommended — see below)
- Portal base URL / API URL: optional overrides (defaults: https://www.solarkcloud.com and https://p2.api.solarkcloud.com)
- Scan Interval: 30 (seconds)
Click SUBMIT

After install you can change discovery, URLs, scan interval and write access under Configure on the integration.

3. API Endpoint Discovery

Sol-Ark has moved its cloud API between hosts more than once (most recently from ecsprod-api-new.solarkcloud.com to p2.api.solarkcloud.com), which breaks integrations pinned to a fixed host.

With Auto-discover API URL enabled (the default), the integration reads the API root the web portal itself uses out of the portal's frontend bundle at each startup, so a future host move is picked up automatically. The resolved URL is stored on the config entry and shown in Configure.

If discovery fails — no internet, portal layout change — the integration logs a warning and falls back to the API URL field, so it keeps working. Turn auto-discover off to pin that field yourself. Config entries created against retired hosts are rewritten to the current defaults on upgrade.

4. Verify

Go to Developer Tools → States
Search solark
Verify 18 sensors with live data

⚙️ Inverter Configuration

The integration exposes inverter settings as read-only diagnostic sensors (visible under "Diagnostic" in the device page) and provides a service for making changes.

Diagnostic Sensors

All settings are displayed as read-only sensors with entity_category: diagnostic:

Power limits: Max Solar Power, Zero Export Power, Max Sell Power
Modes: Work Mode, Energy Mode, Solar Sell, Time of Use
Time slots 1-6: Time, Power, SOC, Mode
Day toggles: Monday through Sunday

Configuring the Inverter

Use the solark.configure_inverter service to change settings. Only specify the parameters you want to change - others remain unchanged.

Safety default: write access is disabled by default.

To enable writes:

Open Settings → Devices & Services → SolArk Cloud
Click Configure
Toggle Allow write access

Action: `solark.configure_inverter`

Call via Developer Tools → Actions or automations:

action: solark.configure_inverter
data:
  # Power limits (all optional)
  max_solar_power: 5000      # 500-19500 W
  zero_export_power: 50      # 0-500 W
  max_sell_power: 8000       # 500-32000 W

  # Boolean toggles
  solar_sell: true
  time_of_use: true

  # Modes
  work_mode: grid_selling    # grid_selling, limited_to_load, limited_to_home
  energy_mode: battery_first # battery_first, load_first

  # Time slot configuration (slots 1-6)
  slot1_time: "06:00"
  slot1_power: 3000          # 0-14000 W
  slot1_soc: 20              # 0-100 %
  slot1_mode: charge         # off, sell, charge, both

  # Day toggles for time-of-use schedule
  monday: true
  tuesday: true
  # ... etc

Benefits of action-based configuration:

Atomic: All changes sent in a single API call
Safe: Dashboard visitors cannot accidentally change settings
Scriptable: Easy to use in automations and scripts
Explicit: Changes require intentional action

🧪 CLI Testing (Optional)

If you want to test the SolArk Cloud API from your machine:

Copy solark_secrets.template.json to solark_secrets.json
Fill in your Sol-Ark username/password and Plant ID
Run:

python -m solark_cli --secrets solark_secrets.json --combined --parsed

⚡ Energy Dashboard Setup

Your integration is fully compatible with Home Assistant's Energy dashboard! Grid import/export and battery charge/discharge energy sensors are provided directly by the integration, so no helper setup is required.

Quick Setup

Settings → Dashboards → Energy
Solar Production → Add Production
- Select: sensor.solark_energy_total
Grid Consumption:
- Select sensor.solark_grid_import_energy
Grid Return (if you export):
- Select sensor.solark_grid_export_energy

📚 Full Guide: See ENERGY_DASHBOARD_SETUP.md for complete instructions including battery tracking.

📱 Dashboard Examples

Power Flow Dashboard

Beautiful real-time monitoring with dynamic power flow indicators:

Features:

Live power values with color coding
Battery status with dynamic icons
24-hour historical charts
Energy production statistics

Requirements:

Mushroom Cards (HACS)
ApexCharts Card (HACS)

Installation:

Option A - UI Method:

Copy dashboards/solark_flow.yaml content
Settings → Dashboards → + ADD DASHBOARD
⋮ → Edit Dashboard → ⋮ → Raw configuration editor
Paste and save

Option B - YAML File:

Copy solark_flow.yaml to /config/dashboards/
Add to configuration.yaml:

lovelace:
  mode: storage
  dashboards:
    solark-power:
      mode: yaml
      title: SolArk Power Flow
      icon: mdi:solar-power
      show_in_sidebar: true
      filename: dashboards/solark_flow.yaml

Restart Home Assistant

🤖 Automation Examples

Low Battery Alert

automation:
  - alias: "Low Battery Warning"
    trigger:
      platform: numeric_state
      entity_id: sensor.solark_battery_soc
      below: 20
    action:
      action: notify.mobile_app
      data:
        title: "Low Battery"
        message: "Battery at {{ states('sensor.solark_battery_soc') }}%"

Excess Solar Notification

automation:
  - alias: "Exporting to Grid"
    trigger:
      platform: numeric_state
      entity_id: sensor.solark_grid_export_power
      above: 2000
      for: "00:05:00"
    action:
      action: notify.mobile_app
      data:
        message: "Exporting {{ states('sensor.solark_grid_export_power') }}W"

Battery Full Alert

automation:
  - alias: "Battery Fully Charged"
    trigger:
      platform: numeric_state
      entity_id: sensor.solark_battery_soc
      above: 95
    condition:
      condition: numeric_state
      entity_id: sensor.solark_battery_power
      below: 100
    action:
      action: notify.mobile_app
      data:
        message: "Battery full at {{ states('sensor.solark_battery_soc') }}%"

📐 Template Sensors

Self-Consumption Percentage

template:
  - sensor:
      - name: "Solar Self-Consumption"
        unit_of_measurement: "%"
        state: >
          {% set pv = states('sensor.solark_pv_power') | float(0) %}
          {% set export = states('sensor.solark_grid_export_power') | float(0) %}
          {% if pv > 0 %}
            {{ ((pv - export) / pv * 100) | round(1) }}
          {% else %}
            0
          {% endif %}

Battery Status Text

template:
  - sensor:
      - name: "Battery Status"
        state: >
          {% set power = states('sensor.solark_battery_power') | float(0) %}
          {% if power > 100 %}
            Discharging
          {% elif power < -100 %}
            Charging
          {% else %}
            Idle
          {% endif %}

🔧 Troubleshooting

Data Fetch Health (Repairs)

The integration monitors each data source it polls (live flow data and inverter work data such as AC Relay Status). If any source keeps failing for over an hour, a notification appears under Settings → System → Repairs describing which data is affected and what to check. The repair issue clears automatically once data starts flowing again — there is never more than one issue per data source.

Integration Won't Connect

Verify credentials at solarkcloud.com (portal replaced mysolark.com)
Confirm Plant ID is correct (from /plants/overview/{id}/...)
Leave Auto-discover API URL enabled, or set API URL to https://p2.api.solarkcloud.com
Check logs: Settings → System → Logs

PV Power Stays at 0 While Portal Shows Production

On microinverter / AC-coupled plants, string pvPower may be 0 while minPower carries production
Version 5.0.2+ adds minPower into sensor.solark_pv_power — update and reload if you still see 0

Grid Import/Export Stay at 0

Plants without an external meter do not populate meterA/B/C
Version 5.0.2+ derives import/export from flow gridOrMeterPower + gridTo/toGrid
Update/reload, then recreate Riemann helpers if needed for the Energy dashboard

Sensors Show "Unavailable"

Check SolArk Cloud service status
Increase scan interval to 60 seconds
Reload integration
Check Settings → System → Logs for custom_components.solark (credentials/tokens are redacted in SolArk debug output)

Grid Power Entity ID Looks Wrong

Fresh installs create the net grid power entity as sensor.solark_grid_power.
Installs upgraded from older versions may have sensor.solark_grid_power_net (or a custom id). The integration keeps whatever id the entity already has so existing automations and dashboards are never broken; rename it manually in Settings → Devices & Services → Entities if you prefer the new form.

Dashboard Shows Blank

Verify sensors exist: Developer Tools → States
Install Mushroom Cards and ApexCharts Card
Restart Home Assistant
Clear browser cache (Ctrl+Shift+R)

Energy Dashboard Issues

Wait 1-2 hours for statistics to build
Verify sensor.solark_energy_total has data
Check sensor has state_class: total_increasing
See ENERGY_DASHBOARD_SETUP.md

Enable Debug Logging

# configuration.yaml
logger:
  logs:
    custom_components.solark: debug

Then check Settings → System → Logs.

Username, password, and OAuth tokens are redacted from SolArk log messages. The integration no longer writes a separate solark_debug.log file.

🏗️ Technical Details

Architecture

Uses DataUpdateCoordinator for efficient polling
OAuth 2.0 password grant against {api_url}/oauth/token (client_id: csp-web)
Optional auto-discovery of VUE_APP_BASE_API from the SolArk portal frontend
Combines data from:
- Energy flow: /api/v1/plant/energy/{plant_id}/flow (powers, SOC, direction flags, minPower)
- Plant realtime: /api/v1/plant/{plant_id}/realtime (etoday / etotal)
- Inverter list + dy/store/{sn}/read (SN lookup, meters when present)

Defaults

Portal: https://www.solarkcloud.com
API: https://p2.api.solarkcloud.com (fallback if discovery fails)
Obsolete hosts (mysolark.com, ecsprod-api-new.solarkcloud.com) are migrated automatically on reload

Statistics Support

Power sensors: state_class: measurement
Energy sensors: state_class: total_increasing
Long-term statistics automatically recorded
Compatible with Energy dashboard

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create feature branch
Make changes with tests
Submit Pull Request

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Community: Home Assistant Forums

📄 License

Provided as-is with no warranty. Use at your own risk.

🙏 Acknowledgments

Home Assistant community
Sol-Ark for API access
All contributors

📝 Changelog

See CHANGELOG.md for version history.

Note: Not officially affiliated with Sol-Ark. Community-developed integration.

Version: 5.3.0 | Supports: Sol-Ark 5K/8K/12K/15K | HA: 2024.3.0+

Name		Name	Last commit message	Last commit date
.claude		.claude
custom_components/solark		custom_components/solark
solark_cli		solark_cli
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLI.md		CLI.md
ENERGY_DASHBOARD_SETUP.md		ENERGY_DASHBOARD_SETUP.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
hacs.json		hacs.json
solark_secrets.template.json		solark_secrets.template.json

Latest commit

History

Folders and files

Repository files navigation