Installation & Setup¶

Setting up the integration has three parts: create an iSolarCloud OpenAPI application, install the integration via HACS, then add and authorize it in Home Assistant.

No cloud account? Use local Modbus

You don't strictly need an iSolarCloud application if you only want read-only sensors over your LAN. Install via HACS (step 2 below), and Home Assistant will auto-discover your WiNet-S dongle for a cloud-free local setup. See Local Modbus (WiNet-S) for the transport modes and current limitations.

1. Create an iSolarCloud OpenAPI application¶

The integration talks to iSolarCloud's OpenAPI, which requires your own application credentials.

Go to the iSolarCloud Developer Portal (developer-api.isolarcloud.com) and sign in with your iSolarCloud account.
Under Applications, create a new application and enable OAuth 2.0 — the Home Assistant flow uses the OAuth 2.0 authorization-code grant (browser redirect + code exchange), so authorization fails if OAuth 2.0 is not enabled for the app.
Note the three credentials it issues: App Key, App Secret, and App ID.
Set the application's redirect / callback URL to your Home Assistant callback:
```
https://<your-home-assistant>/api/sungrow_hass/callback
```
Use the same external URL you reach Home Assistant on (the one in Settings → System → Network → Home Assistant URL). 5. Authorize your plant to the application (Power Station Sharing in iSolarCloud), so the app can read its data.

Application review

A newly created application can take a few working days to be approved before its credentials work. Also make sure your app is registered on the same region as your account.

Keep your App ID private

Anyone who knows your App ID can authorize their plant to your application. Don't publish it in screenshots, issues, or documentation.

2. Install via HACS¶

In Home Assistant, open HACS.
Search for Sungrow iSolarCloud and download it. (If it isn't listed yet, add https://github.com/KRoperUK/sungrow-hass as a custom repository of type Integration.)
Restart Home Assistant.

Pre-release / PR builds (optional)¶

CI publishes prerelease GitHub Releases when component-impacting PRs or main pushes go green:

Kind	Tag shape	Install
Main RC	`vX.Y.Z-rc.N`	HACS pre-releases, or download `sungrow.zip` from the release
PR build	`vX.Y.Z-pr.<PR>.<run>`	Same; tag points at a synthetic commit that only rewrites `manifest.json` / `const.VERSION` so HACS sorts above the last stable

Enable Show beta versions (pre-releases) for this repository in HACS if you intend to dogfood. Prefer a specific pre-release tag over a floating branch tip. PR pre-releases are deleted when the PR closes; do not rely on them long-term.

3. Add and authorize the integration¶

Setup is two-phase: Home Assistant creates the hub entry first (so the OAuth callback endpoint exists before any redirect — this avoids a first-install 404), then walks you through authorization. At a glance:

sequenceDiagram
    autonumber
    actor You
    participant HA as Home Assistant
    participant SC as iSolarCloud
    You->>HA: Add integration → region + App Key/Secret/ID
    HA->>HA: Create hub entry, register callback view
    HA-->>You: Open iSolarCloud authorization page
    You->>SC: Sign in and approve the app
    SC-->>HA: Redirect to /api/sungrow_hass/callback?code=…
    HA->>SC: Exchange code for tokens
    SC-->>HA: Access + refresh tokens
    HA->>HA: Persist tokens, discover plants, create entities

Go to Settings → Devices & Services → Add Integration and choose Sungrow iSolarCloud.
Select your Gateway region (Europe, International, China, or Australia — it must match the region your devices are physically connected to).
Enter your App Key, App Secret, and App ID exactly as issued — with no surrounding quotes or spaces.
You'll be sent to iSolarCloud to authorize the application in your browser. Approve it; you are redirected back and Home Assistant stores the tokens.

Manual authorization fallback

If the automatic redirect doesn't complete, the flow shows a link and a box — open the link, approve, then paste the code (or the full redirect URL) back into Home Assistant. Authorization codes are single-use, so use a fresh one if it says "invalid".

Once authorized, the integration discovers your plant(s) and creates the sensors. See Configuration to tune polling and enable extra points, or Troubleshooting if entities don't appear.

Changing region or credentials later

Use Reconfigure on the integration entry to update the region or API credentials. The App ID is fixed for an entry — if you retire an app and create a new App ID, remove the integration and add it again rather than reconfiguring.