Sungrow API Client

API Client which uses the official API from the sungrow developer portal.

The Client is still in development and not finished.

Note

Pull requests to complete APIs are welcome

Important

I choose a very simple implementation to get this client used in different environments; without coming to "dependency hell".

ToDos

• Add gitHub actions for compile, dependabot and securiy issues
• Add sample client for basic usage
• Support encrypted API calls (open: Change password for each call)
• Add release action
• Mock JUnit Test
• Deploy via Maven Central
• Complete API Calls for reading
• Add OAuth2 Support
• Complete API Calls for writing

Dependency

The JAR is available on Maven Central with the coordinates io.github.afrouper:sungrow-api-client:

<dependency>
    <groupId>io.github.afrouper</groupId>
    <artifactId>sungrow-api-client</artifactId>
    <version>[1.1.0,)</version>
</dependency>

Usage

You have to create an account at Sungrows iSolarCloud and on their developer portal and get the needed credentials (see Sungrow Developer Portal) To access the iSolarCloud API you can either use a variant with an "API key" or via OAuth2.

For a simple configuration approach the needed values can be read via class EnvironmentConfiguration.

SystemProperty / Environment variable	meaning
APP_KEY	Your app key from Sungrow Developer Portal
SECRET_KEY	Your secret key from Sungrow Developer Portal
ACCOUNT_EMAIL	EMailadress used for login to Sungrow Developer Portal
ACCOUNT_PASSWORD	Password used for login to Sungrow Developer Portal
RSA_PUBLIC_KEY	RSA Public key to call APIs E2E encrypted
API_CALL_PASSWORD	Password for payload encryption
AUTHORIZE_URL	OAuth2 Authorization URL
REDIRECT_URL	OAuth2 Redirect URL

The URL for accessing the correct cloud service is determined from the Region Enum.

API Key variant

A simple example can be found at Client.java. Its Output (with a german installation) can be seen here

sungrowClient = new SungrowClientBuilder()
    .builder(SungrowClientBuilder.Region.EUROPE)
    .withCredentials(EnvironmentConfiguration.getAppKey(), EnvironmentConfiguration.getSecretKey())
        .withLogin(EnvironmentConfiguration.getAccountEmail(), EnvironmentConfiguration.getAccountPassword());

PlantList plants = sungrowClient.getPlants();
// Handle Plants and devices - see de.afrouper.server.sungrow.Client

OAuth2 variant

The OAuth2 auth code flow requires a server to handle the redirect send after login; the server must be implemented or provided by you 😇 A sample can be found at OAuth2Client

sungrowClient = new SungrowClientBuilder()
    .builder(SungrowClientBuilder.Region.EUROPE)
    .withCredentials(EnvironmentConfiguration.getAppKey(), EnvironmentConfiguration.getSecretKey())
    .withOAuth2(EnvironmentConfiguration.getAuthorizeUrl(), EnvironmentConfiguration.getRedirectUrl())
    .build();

String authCode = "xxxxx"; //TODO: Replace with correct auth code
sungrowClient.authCodeFlow(authCode);

PlantList plants = sungrowClient.getPlants();
// Handle Plants and devices...

sungrowClient.close(); // Stop thread for refreshing the access token

Sungrow Developer Portal

Use your sungrow credentials to login at "https://developer-api.isolarcloud.com". You need to create an application; go to you applications in the top menu:

Click 'Create Application'. This is the sample for a "normal" application - used via "API key" variant.

API Usage

Please read the docs at the Developer Portal. THe are some hints and documentation of the measurement points, etc.