A lightweight Java library for connecting to the official Growatt OpenAPI to fetch live data from Growatt inverters and battery storage systems.

This library is based on the Growatt OpenAPI v1 documentation. The v4 API is currently still buggy and inconsistent, so v1 is used instead.

Growatt's OpenAPI groups devices into several types:

Only the MIN device type is currently implemented. Contributions to add support for the other device types are welcome.

• Simple HTTP client based on java.net.http.HttpClient (no extra HTTP dependencies)
• Automatic JSON mapping of API responses via Jackson
• Typed data model (MinDeviceRealTimeData) with PV, grid, and battery values
• Convenience methods to determine battery state (charging / discharging / idle)
• Dedicated checked exceptions for API and device-lookup errors

• Java 25 or higher
• Maven
• A valid API token for the Growatt OpenAPI

The project is not currently published to Maven Central. Clone the repository and install it into your local Maven repository:

git clone https://github.com/LinzN/growatt-java-api.git
cd growatt-java-api
mvn install

Then add it as a dependency in your project:

<dependency>
    <groupId>de.linzn</groupId>
    <artifactId>growatt-java-api</artifactId>
    <version>0.0.1</version>
</dependency>

import de.linzn.growattJavaApi.GrowattClientApi;
import de.linzn.growattJavaApi.devices.min.MinDeviceRealTimeData;
import de.linzn.growattJavaApi.exceptions.GrowattApiException;
import de.linzn.growattJavaApi.exceptions.GrowattDeviceNotFoundException;

public class Example {
    public static void main(String[] args) throws GrowattApiException, GrowattDeviceNotFoundException {
        GrowattClientApi api = new GrowattClientApi("YOUR_API_TOKEN");

        MinDeviceRealTimeData data = api.getMinDeviceRealTimeData("SERIAL_NUMBER");

        System.out.println("PV power: " + data.getPpv() + " W");
        System.out.println("AC power: " + data.getPac() + " W");
        System.out.println("Battery SOC: " + data.getBmsSoc() + " %");
        System.out.println("Battery state: " + data.getBatteryState());
    }
}

Internally, GrowattClientApi delegates to MinDeviceApiWrapper, which calls the Growatt v1 endpoint /v1/device/tlx/tlxs_data.

Contains, among others, the following values:

• PV: ppv, ppv1, ppv2
• Grid/AC: pac, pacToLocalLoad, pacToGridTotal, pacToUserTotal, powerOfGridTake
• Battery: bmsSoc, bmsSoh, bmsVbat, bmsIbat, bmsTemp1Bat, bdc1ChargePower, bdc1DischargePower, bdc1Vbat, bdc1Ibat, chargePowerOfBattery, disChargePowerOfBattery
• Energy counters: echargeToday, echargeTotal, edischargeToday, edischargeTotal
• Status: status, faultType, warnCode, time, serialNum

The class also provides convenience methods:

data.isCharging();      // true if the battery is currently charging
data.isDischarging();   // true if the battery is currently discharging
data.isIdle();          // true if the battery is idle
data.getBatteryState(); // returns CHARGING, DISCHARGING, or IDLE

Enum with the values CHARGING, DISCHARGING, IDLE.

GrowattClientApi.getMinDeviceRealTimeData declares two checked exceptions:

• GrowattApiException – thrown on an HTTP transport error, an HTTP status other than 200, a non-zero error_code in the API response, or a JSON parsing failure.
• GrowattDeviceNotFoundException – thrown when no data record is found for the given serial number.

This project is licensed under the GNU Lesser General Public License v3.0 (LGPLv3).

Niklas Linz – MirraNET Contact: [email protected]

This is an unofficial project and is not affiliated with Growatt. Use at your own risk.