1 unstable release
new 0.1.0 | Apr 26, 2025 |
---|
#506 in Web programming
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 usernameGROWATT_PASSWORD
: Your Growatt account passwordGROWATT_BASE_URL
(optional): Alternative base URLGROWATT_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