#energy #solar #inverter #api-bindings #growatt

bin+lib growatt

Rust client for the Growatt API

1 unstable release

new 0.1.0 Apr 26, 2025

#506 in Web programming

MIT license

43KB
767 lines

Growatt API Rust

A Rust client for interacting with the Growatt API. This library allows you to:

  • Login and authenticate with the Growatt server
  • Retrieve plant and device information
  • Get energy statistics (daily, monthly, yearly, total)
  • Access mix status and battery statistics
  • Retrieve fault logs and other device information

Installation

Add this to your Cargo.toml:

[dependencies]
growatt = "0.1.0"

Quick Start

use growatt::Growatt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new client
    let mut client = Growatt::new();

    // Login
    if client.login("your_username", "your_password").await? {
        println!("Login successful!");

        // Get plants
        let plants = client.get_plants().await?;
        println!("Plants: {:?}", plants);

        // When you're done
        client.logout().await?;
    }

    Ok(())
}

Environment Variables Configuration

You can initialize the client with environment variables for easier configuration:

use growatt_api_rust::Growatt;
use dotenv::dotenv;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load from .env file and environment
    dotenv().ok();

    // Create client with env vars (GROWATT_USERNAME, GROWATT_PASSWORD, etc.)
    let mut client = Growatt::from_env();

    // Auto-login using credentials from environment
    if client.check_login().await? {
        // Your code here
    }

    Ok(())
}

Expected environment variables:

  • GROWATT_USERNAME: Your Growatt account username
  • GROWATT_PASSWORD: Your Growatt account password
  • GROWATT_BASE_URL (optional): Alternative base URL
  • GROWATT_SESSION_DURATION (optional): Session duration in minutes

Client Initialization Options

Standard Initialization

// Create with default options
let client = Growatt::new();

Alternative Server URL

// Use an alternative API server
let client = Growatt::new().with_alternate_url();

Custom Session Duration

// Set a custom session duration (60 minutes)
let client = Growatt::new().with_session_duration(60);

Authentication

Login

// Login with username and password
let success = client.login("username", "password").await?;

Logout

// Properly terminate the session
let success = client.logout().await?;

Authentication Status

// Check if currently logged in
if client.is_logged_in() {
    // User is authenticated
}

Core API Methods

Plant Management

// Get all plants for the account
let plants = client.get_plants().await?;

// Get detailed information about a specific plant
let plant_details = client.get_plant("plant_id").await?;

// Get weather information for a plant
let weather = client.get_weather("plant_id").await?;

Device Management

// Get list of MIX device IDs for a plant
let mix_ids = client.get_mix_ids("plant_id").await?;

// Get detailed device list for a plant
let devices = client.get_device_list("plant_id").await?;

// Get devices with pagination
let devices_page = client.get_devices_by_plant_list("plant_id", Some(1)).await?;

Mix Device Data

// Get total measurements from a specific MIX
let mix_total = client.get_mix_total("plant_id", "mix_sn").await?;

// Get current status of a MIX device
let mix_status = client.get_mix_status("plant_id", "mix_sn").await?;

// Update MIX AC discharge time period
let result = client.post_mix_ac_discharge_time_period_now("plant_id", "mix_sn").await?;

Energy Statistics

// Get daily energy statistics
let daily_stats = client.get_energy_stats_daily("2025-04-26", "plant_id", "mix_sn").await?;

// Get monthly energy statistics
let monthly_stats = client.get_energy_stats_monthly("2025-04", "plant_id", "mix_sn").await?;

// Get yearly energy statistics
let yearly_stats = client.get_energy_stats_yearly("2025", "plant_id", "mix_sn").await?;

// Get total energy statistics
let total_stats = client.get_energy_stats_total("2025", "plant_id", "mix_sn").await?;

Battery Statistics

// Get weekly battery statistics
let battery_stats = client.get_weekly_battery_stats("plant_id", "mix_sn").await?;

Fault Logs

// Get fault logs with detailed parameters
let fault_logs = client.get_fault_logs(
    "plant_id",      // Plant ID
    Some("2025-04-26"),  // Date (optional)
    "device_sn",     // Device serial number
    1,               // Page number
    0,               // Device flag (0 = All)
    0                // Fault type (0 = All)
).await?;

// Using the alias method (identical functionality)
let fault_logs = client.get_plant_fault_logs(
    "plant_id", Some("2025-04-26"), "device_sn", 1, 0, 0
).await?;

Error Handling

The library uses a custom error type GrowattError which covers various error scenarios:

// Example of error handling
match client.login("username", "password").await {
    Ok(success) => {
        if success {
            println!("Login successful");
        } else {
            println!("Login failed");
        }
    },
    Err(err) => match err {
        GrowattError::AuthError(msg) => println!("Authentication error: {}", msg),
        GrowattError::RequestError(err) => println!("Network error: {}", err),
        GrowattError::JsonError(err) => println!("JSON parsing error: {}", err),
        GrowattError::InvalidResponse(msg) => println!("Invalid API response: {}", msg),
        GrowattError::NotLoggedIn => println!("Not logged in"),
    }
}

Data Structures

The library provides structured access to Growatt data:

// Example of working with plant data
let plants = client.get_plants().await?;
for plant in plants.0 {
    println!("Plant ID: {}", plant.plant_id);
    println!("Plant Name: {}", plant.plant_name);

    if let Some(address) = plant.plant_address {
        println!("Address: {}", address);
    }

    if let Some(power) = plant.plant_watts {
        println!("Power: {} W", power);
    }
}

// Example of working with plant details
let plant_details = client.get_plant("plant_id").await?;
if let Some(total_energy) = plant_details.total_energy {
    println!("Total Energy: {} kWh", total_energy);
}

Advanced Usage

Session Management

The library automatically handles session expiry and renewal:

// The client will automatically re-authenticate if needed
client.get_plants().await?;

Token Access

// Get the authentication token (if needed for external use)
if let Some(token) = client.get_token() {
    println!("Current token: {}", token);
}

License

MIT

Dependencies

~8–21MB
~301K SLoC