Saltar al contenido principal

Integración domótica Sungrow iSolarCloud, gratuita y de código abierto

Integración Sungrow iSolarCloud para Gladys Assistant

Unofficial: Sungrow solar and batteries via iSolarCloud, read only: power, energy, grid, battery.

Ver en GitHubTodas las integraciones
info

La documentación de esta integración la escribe su autor y, por ahora, solo está disponible en inglés.

This integration reads your Sungrow inverters and batteries through the official iSolarCloud OpenAPI, read only: nothing is ever commanded (no battery mode, no feed-in limit).

Unofficial connector, not affiliated with Sungrow. Never tested with a real account on iSolarCloud, and never tested with a real device (inverter, battery) yet: it follows the pysolarcloud library (MIT), used by Home Assistant. Feedback is welcome on the Gladys forum. Sungrow and iSolarCloud are trademarks of their owner.

What you get​

For each plant you authorize, up to three devices:

DeviceFeatureUnit / type
Plant (always)Solar powerW, production
Solar production (index)kWh, production index
Solar production (30 minutes)kWh, filled by Gladys
Solar production todayplain sensor (kWh)
Home consumption power, today and totalplain sensors (W, kWh)
Grid (when iSolarCloud gives it)Energy bought from the grid (index)kWh, consumption index
Grid power (sign as given by iSolarCloud)plain sensor (W)
Bought today, fed in today and in totalplain sensors (kWh)
Battery (when iSolarCloud gives it)Battery charge%
Battery powerplain sensor (W)
Charged and discharged, today and in totalplain sensors (kWh)

The two energy indexes​

  • Solar production (index): the total produced by the plant since it was commissioned. It comes with the Solar production (30 minutes) feature, which Gladys fills itself from the index (the integration never writes to it): that one feeds the energy monitoring.
  • Energy bought from the grid (index): the total bought from the grid, counted by Gladys as electricity consumption (with its cost, according to your energy contract in Gladys).

If another meter already feeds Gladys (Linky, P1, a Zigbee meter…), do not add the "grid" device: the same consumption would be counted twice. The "plant" device is useful on its own.

Both indexes go through a guard (the same as the P1 Monitor integration) before they reach Gladys, because Gladys counts every rise in full:

  • a value of 0, or an absent one, is never sent;
  • a plausible rise (no more than the maximum power of the installation since the previous read, 36 kW by default) goes through;
  • a drop or a jump is never confirmed by time nor by repetition: the value is held back (the last accepted value is sent again), the status of the integration shows it, and it stays held across a restart;
  • if the value held back is right (a replaced meter, a reset), click Accept the held indexes: it is taken at the next read, once, and only if it is the value shown (plus what may have been produced or drawn meanwhile).

Every other total and daily value is a plain sensor: Gladys counts it nowhere.

Step 1: create your Sungrow developer app​

The iSolarCloud API needs a developer app you create yourself, once, on the Sungrow portal. The four steps below are those of the pysolarcloud library:

  1. Create an account on the iSolarCloud developer portal: https://developer-api.isolarcloud.com/.
  2. Create an application in the portal:
    • to "authorize with OAuth2.0", answer Yes;
    • give a Redirect URL (it can be changed later): the address iSolarCloud sends your browser back to after the authorization. Two options:
      • the return address of your Gladys (recommended). To find it: do step 2 below without a redirect URL, click Connect once: the status of the integration shows "The return address of this Gladys is …". Copy it into the portal;
      • another https address of yours: you will then copy and paste the final address (see below).
  3. Wait for Sungrow to approve the app.
  4. In the portal, note:
    • the Appkey;
    • the Secret Key;
    • the Application Id: it appears in the authorize URL the portal shows, after applicationId= (a number).

Not checked, according to other projects: the portal may also accept the credentials of your Sungrow account (try them before creating a new one); how long the approval takes and how the portal shows it are not known.

Step 2: configure the integration​

In Integrations → Sungrow iSolarCloud → Configuration:

  1. iSolarCloud server: the one of your account (Europe for France, Belgium, Switzerland). Not checked: the developer app is probably tied to the same server.
  2. Appkey, Secret Key, Application Id: those of step 1.
  3. Leave Redirect URL empty if the app sends back to Gladys; otherwise enter the address registered in the portal.
  4. Save.

Step 3: authorize​

  1. Click Connect: the iSolarCloud page opens.
  2. Sign in with your usual iSolarCloud account. Your password is typed on the iSolarCloud page only: the integration never sees it.
  3. Tick the plant(s) to share, then authorize.
  4. iSolarCloud sends you back to Gladys: the integration reads your plants. Add the devices from the Discovery tab.

With another redirect URL​

  1. After the authorization, the browser ends on your address (the page may show an error, that is expected). Copy the whole address from the address bar: it holds code= and state=.
  2. Paste it into the Finish the authorization action, within 15 minutes. It must start with the configured redirect URL: another address is refused (the authorization then stays usable).

An authorization started serves once. If iSolarCloud is slow to answer (more than 3.5 seconds on the return to Gladys), the integration shows "iSolarCloud is slow to answer: click Connect again": start again.

What the integration keeps​

  • The Secret Key is kept by Gladys in its database, as any configuration value: never shown again, sent only to iSolarCloud.
  • The iSolarCloud tokens (access and renewal) are kept in clear in the file /data/sungrow-state.json of the integration's volume, readable by its container only (mode 0600), and sent only to iSolarCloud. The same file keeps the pauses, the stops, the list of plants, the number of requests of the day and the state of the index guards. No password is ever written there.

Pace and API limits​

  • iSolarCloud updates its data every 5 minutes: the integration reads all the plants in one request, every 5 minutes by default (5 minutes at least, 60 at most).
  • The list of plants is read again every 6 hours (and on request from Discovery).
  • The token is renewed by a timer a little before its end, never twice within a minute.
  • At most 600 requests a day (UTC) in all, authorization and renewals included: about 320 at the default pace. If that ceiling is reached (it never should), everything waits for the next day.
  • After a restart, the first read waits for the end of the interval since the last read and for the end of a running pause.

Sungrow publishes no figures for its rate limits: the integration answers a refusal (HTTP 429 or a "too frequent" answer) with a pause.

Errors and stops​

SituationWhat the integration does
iSolarCloud asks to slow down (HTTP 429, "too frequent")pause of 1 minute to 6 hours (15 minutes by default), kept across a restart
iSolarCloud unavailable (5xx error, "busy")pause of 5 minutes to 1 hour, kept across a restart
Daily ceiling of requests reachedpause until the next day (midnight UTC)
Network down, unexpected answernew try after the interval, then 5, 15, 30 minutes, kept across a restart
One plant without datathe others go on; its devices turn "unreachable"
Renewal refused by iSolarCloud"session ended" stop, kept: click Connect
Access refused even with a new token, or keys refusedstop, kept: check the keys, then Connect or "Test iSolarCloud"

The integration never reconnects by itself and never retries a refusal: only a click does. The Test iSolarCloud button never reads faster than the interval nor during a pause: it shows the last result and when the next read comes, and reads only once the interval has passed since the last read. After an "access refused" stop it reads at once, once (that is how the stop is lifted). Once every 30 seconds at most.

Troubleshooting​

  • "Enter the app key": Appkey, Secret Key or Application Id missing (the Application Id is a number).
  • iSolarCloud refuses the authorization: wrong server, Appkey, Secret Key or redirect URL, app not yet approved by Sungrow, or a pasted address older than 15 minutes.
  • No plant: click Connect again and tick the plant on the iSolarCloud page.
  • An index held back: see "The two energy indexes" above.
  • A feature stays empty: not every plant gives every measure point (it depends on the inverter model and the meter).

Limits​

  • Read only: no command (no battery, no feed-in).
  • The values come from the iSolarCloud cloud (updated every 5 minutes), not from the inverter locally.
  • The sign of the grid and battery powers is the one of iSolarCloud, not checked.
  • Never tested with a real account nor a real device: the measure points and units follow pysolarcloud 0.5.0.

Parámetros de configuración​

Estos son los parámetros que Sungrow iSolarCloud te pide en su pantalla de configuración en Gladys.

ParámetroTipoObligatorioDescripción
Sungrow plants in GladyssectionNoUnofficial connector, not affiliated with Sungrow. It reads your Sungrow inverters and batteries through the official iSolarCloud OpenAPI, read only: solar power and production, home consumption, energy bought from and fed into the grid, battery charge and power. The solar production and the energy bought are energy indexes, checked before Gladys counts them. It needs a developer app you create yourself on the Sungrow developer portal (approved by Sungrow): follow the guide. Your password is typed on the iSolarCloud page only. Never tested yet with a real account. Sungrow and iSolarCloud are trademarks of their owner.
1. Your developer appsectionNoOn the Sungrow developer portal, create an account, then an app: answer Yes to "authorize with OAuth2.0" and give a redirect URL (the return address of this Gladys, shown here after a first click on Connect, or another address of yours). Wait for Sungrow to approve it. Then copy its Appkey, its Secret Key and its Application Id (the applicationId= of the authorize URL of the portal) below, choose the server of your iSolarCloud account, and save.
iSolarCloud serverselectNoThe server of your account and of your developer app (Europe for France, Belgium, Switzerland).
AppkeystringSíThe Appkey of your developer app.
Secret KeysecretSíThe Secret Key of your developer app. Kept by Gladys in its database, never shown again, sent only to iSolarCloud.
Application IdstringSíThe number after applicationId= in the authorize URL the portal shows for your app.
2. AuthorizesectionNoClick Connect: the iSolarCloud page opens; sign in, tick your plant(s) and authorize. iSolarCloud sends you back to Gladys and the integration reads your plants. If the redirect URL of your app is not this Gladys, write it in "Redirect URL": at the end, copy the whole address the browser shows (it holds code= and state=) and paste it into "Finish the authorization" below, within 15 minutes. The tokens are kept in clear in the /data volume of the integration (readable by its container only), sent only to iSolarCloud.
Redirect URL (optional)stringNoEmpty: iSolarCloud sends you back to this Gladys. Otherwise the redirect URL of your developer app (https, or http on localhost only): finish by pasting the address the browser ended on.
iSolarCloud accountoauth2NoOpens the iSolarCloud authorization page (save the keys first).
Refresh interval (minutes)numberNoiSolarCloud updates its data every 5 minutes: one request per read for all the plants, at most 600 requests a day.
Maximum power of the installation (kW)numberNoThe most the plant may produce or the home draw from the grid. An index that rises faster, or drops, is held back until you accept it.
Language of the names and textsselectNo

Cómo instalar Sungrow iSolarCloud en Gladys​

  1. En Gladys, abre Integraciones: Sungrow iSolarCloud aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
  2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/lm1lc3n7/gladys-sungrow:0.1.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
  3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
  4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/LM1LC3N7/gladys-sungrow.

Sungrow iSolarCloud requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.

¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.

Sobre las integraciones externas​

Sungrow iSolarCloud es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene LM1LC3N7, no el equipo principal de Gladys.

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂
Última actualización en