solaredge

package module
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 25, 2024 License: MIT Imports: 12 Imported by: 1

README

solaredge

GitHub tag (latest by date) Codecov Build Go Report Card GitHub GoDoc

Go API for SolarEdge power inverters.

Authors

  • Christophe Lambin

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Documentation

Overview

Package solaredge is a client library for the SolarEdge Cloud-Based Monitoring Platform. The API gives access to data saved in the monitoring servers for your installed SolarEdge equipment and its performance (i.e. generated power & energy).

The implementation is based on SolarEdge's official API documentation.

The current version of this library implements the following sections of the API:

  • Site Data API
  • Site Equipment API
  • API Versions

Access to SolarEdge data is determined by the user's API Key & installation. If your situation gives you access to the Accounts List, Meters or Sensors API, feel free to get in touch to get these implemented in this library.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError added in v0.8.0 

type APIError struct {
	Message string
}

An APIError indicates the SolarEdge API server rejected the request (returning 403 - Forbidden).

Apart from providing an invalid API key, this happens when the request arguments are not permitted, e.g. calling GetSiteEnergy() with a timeUnit of "DAY" and a time range of more than a year.

WARNING: the SolarEdge API returns the error as an HTML document. APIError does its best to parse the document, but this may break at some point.

func (*APIError) Error added in v0.8.0 

func (e *APIError) Error() string

Error returns a string representation of an APIError

func (*APIError) Is added in v0.8.0 

func (e *APIError) Is(e2 error) bool

Is returns true if e2 is a ParseError

type Battery added in v0.8.0 

type Battery struct {
	Nameplate      int    `json:"nameplate"`
	SerialNumber   string `json:"serialNumber"`
	ModelNumber    string `json:"modelNumber"`
	TelemetryCount int    `json:"telemetryCount"`
	Telemetries    []struct {
		TimeStamp                Time    `json:"timeStamp"`
		Power                    float64 `json:"power"`
		BatteryState             int     `json:"batteryState"`
		LifeTimeEnergyCharged    float64 `json:"lifeTimeEnergyCharged"`
		LifeTimeEnergyDischarged float64 `json:"lifeTimeEnergyDischarged"`
		FullPackEnergyAvailable  float64 `json:"fullPackEnergyAvailable"`
		InternalTemp             float64 `json:"internalTemp"`
		ACGridCharging           float64 `json:"ACGridCharging"`
	} `json:"telemetries"`
}

Battery contains detailed storage information from batteries: the state of energy, power and lifetime energy.

type BatteryEquipment added in v0.8.0 

type BatteryEquipment struct {
	Name                string  `json:"name"`
	Manufacturer        string  `json:"manufacturer"`
	Model               string  `json:"model"`
	FirmwareVersion     string  `json:"firmwareVersion"`
	ConnectedInverterSn string  `json:"connectedInverterSn"`
	NameplateCapacity   float64 `json:"nameplateCapacity"`
	SN                  string  `json:"SN"`
}

BatteryEquipment contains a battery's name, model, manufacturer, serial number, etc.

type ChangeLogEntry added in v0.8.0 

type ChangeLogEntry struct {
	Date         Date   `json:"date"`
	PartNumber   string `json:"partNumber"`
	SerialNumber string `json:"serialNumber"`
}

ChangeLogEntry contains an equipment component replacement.

type Client 

type Client struct {
	// Token contains the SolarEdge authentication token
	Token string
	// HTTPClient specifies the http client to use. Defaults to http.DefaultClient
	HTTPClient *http.Client
}

Client to interact with the SolarEdge API

func (*Client) GetCurrentAPIVersion added in v0.8.0 

func (c *Client) GetCurrentAPIVersion(ctx context.Context) (string, error)

GetCurrentAPIVersion returns the current API version used by the SolarEdge API server.

func (*Client) GetSites added in v0.8.0 

func (c *Client) GetSites(ctx context.Context) (Sites, error)

GetSites returns all sites registered under the account associated with the supplied API Token.

Example 
package main

import (
	"context"
	"fmt"
	"github.com/clambin/solaredge"
	"os"
)

func main() {
	ctx := context.Background()
	c := solaredge.Client{Token: os.Getenv("SOLAREDGE_APIKEY")}

	sites, err := c.GetSites(ctx)
	if err != nil {
		panic(err)
	}
	for _, site := range sites {
		fmt.Printf("Site '%s' (%s), Peak Power: %.1f\n", site.Name, site.Status, site.PeakPower)
	}
}

Output:

func (*Client) GetSupportedAPIVersions added in v0.8.0 

func (c *Client) GetSupportedAPIVersions(ctx context.Context) ([]string, error)

GetSupportedAPIVersions returns all API versions supported by the SolarEdge API server.

type CurrentPower added in v1.0.2 

type CurrentPower struct {
	Power float64 `json:"power"`
}

CurrentPower contains the current power output, as contained in PowerOverview

type CurrentPowerFlow added in v0.8.0 

type CurrentPowerFlow struct {
	Unit        string `json:"unit"`
	Connections []struct {
		From string `json:"from"`
		To   string `json:"to"`
	} `json:"connections"`
	Grid    PowerFlowReading `json:"GRID"`
	Load    PowerFlowReading `json:"LOAD"`
	PV      PowerFlowReading `json:"PV"`
	Storage struct {
		Status       string  `json:"status"`
		CurrentPower float64 `json:"currentPower"`
		ChargeLevel  float64 `json:"chargeLevel"`
		Critical     bool    `json:"critical"`
	} `json:"STORAGE"`
}

CurrentPowerFlow contains current power flow between all elements of the site including PV array, storage (battery), loads (consumption) and grid.

type Date added in v0.8.0 

type Date time.Time

Date represents a date (YYYY-MM-DD) in the SolarEdge API.

func (Date) MarshalJSON added in v0.8.0 

func (d Date) MarshalJSON() ([]byte, error)

MarshalJSON marshals a Date into a JSON object

func (Date) String added in v0.8.0 

func (d Date) String() string

String returns a string representation of a Date. This is equivalent to time.Time{}.String()

func (*Date) UnmarshalJSON added in v0.8.0 

func (d *Date) UnmarshalJSON(bytes []byte) error

UnmarshalJSON unmarshals a date in a JSON object to a Date

type Energy added in v0.8.0 

type Energy struct {
	MeasuredBy string  `json:"measuredBy"`
	TimeUnit   string  `json:"timeUnit"`
	Unit       string  `json:"unit"`
	Values     []Value `json:"values"`
}

Energy produced by the site in a time range

type EnergyDetails added in v0.8.0 

type EnergyDetails struct {
	Meters   []MeterReadings `json:"meters"`
	TimeUnit string          `json:"timeUnit"`
	Unit     string          `json:"unit"`
}

EnergyDetails contains site energy measurements from meters such as consumption, export (feed-in), import (purchase), etc.

type EnergyOverview added in v1.0.2 

type EnergyOverview struct {
	Energy  float64 `json:"energy"`
	Revenue float64 `json:"revenue"`
}

EnergyOverview contains the energy produced in PowerOverview

type EnvBenefits added in v0.8.0 

type EnvBenefits struct {
	GasEmissionSaved struct {
		Co2   float64 `json:"co2"`
		Nox   float64 `json:"nox"`
		So2   float64 `json:"so2"`
		Units string  `json:"units"`
	} `json:"gasEmissionSaved"`
	LightBulbs   float64 `json:"lightBulbs"`
	TreesPlanted float64 `json:"treesPlanted"`
}

EnvBenefits lists all environmental benefits based on site energy production: gas emissions saved, equivalent trees planted and light bulbs powered for a day.

type GatewayEquipment added in v0.8.0 

type GatewayEquipment struct {
	Name            string `json:"name"`
	FirmwareVersion string `json:"firmwareVersion"`
	SN              string `json:"SN"`
}

GatewayEquipment contains a gateway's name, model, manufacturer, serial number, etc.

type HTTPError added in v0.5.0 

type HTTPError struct {
	StatusCode int
	Status     string
	Body       []byte
}

HTTPError contains the HTTP error received from the SolarEdge API server

func (*HTTPError) Error added in v0.5.0 

func (e *HTTPError) Error() string

Error returns a string representation of an HTTPError

func (*HTTPError) Is added in v0.5.0 

func (e *HTTPError) Is(e2 error) bool

Is return true if e2 is an HTTPError

type Inventory added in v0.8.0 

type Inventory struct {
	Batteries []BatteryEquipment  `json:"batteries"`
	Gateways  []GatewayEquipment  `json:"gateways"`
	Inverters []InverterEquipment `json:"inverters"`
	Meters    []MeterEquipment    `json:"meters"`
	Sensors   []SensorEquipment   `json:"sensors"`
}

Inventory contains all batteries, gateways, inverters, meters and sensors at a site.

type Inverter added in v0.8.0 

type Inverter struct {
	Manufacturer string `json:"manufacturer"`
	Model        string `json:"model"`
	Name         string `json:"name"`
	SerialNumber string `json:"serialNumber"`
	// contains filtered or unexported fields
}

Inverter contains an inverter's name, model, manufacturer and serial number, as returned by GetInverters.

func (*Inverter) GetSerialNumber added in v0.9.2 

func (i *Inverter) GetSerialNumber() string

GetSerialNumber returns the inverter's SerialNumber

func (*Inverter) GetTelemetry added in v0.9.0 

func (i *Inverter) GetTelemetry(ctx context.Context, from, to time.Time) ([]InverterTelemetry, error)

GetTelemetry returns the measurements of the inverter within the specified time range.

This API is limited to a one-week period. If the time range exceeds one week, an APIError is returned.

NOTE: this may not be fully complete, as data returned for my account doesn't match the specifications.

type InverterEquipment added in v0.8.0 

type InverterEquipment struct {
	SN                  string `json:"SN"`
	CommunicationMethod string `json:"communicationMethod"`
	ConnectedOptimizers int    `json:"connectedOptimizers"`
	CPUVersion          string `json:"cpuVersion"`
	Manufacturer        string `json:"manufacturer"`
	Model               string `json:"model"`
	Name                string `json:"name"`
	// contains filtered or unexported fields
}

InverterEquipment contains an inverter's name, model, manufacturer, serial number, etc, as returned by GetEquipment.

func (*InverterEquipment) GetSerialNumber added in v0.9.2 

func (i *InverterEquipment) GetSerialNumber() string

GetSerialNumber returns the inverter's SerialNumber

func (*InverterEquipment) GetTelemetry added in v0.9.0 

func (i *InverterEquipment) GetTelemetry(ctx context.Context, from, to time.Time) ([]InverterTelemetry, error)

GetTelemetry returns the measurements of the inverter within the specified time range.

This API is limited to a one-week period. If the time range exceeds one week, an APIError is returned.

NOTE: this may not be fully complete, as data returned for my account doesn't match the specifications.

Example 
package main

import (
	"context"
	"fmt"
	"github.com/clambin/solaredge"
	"os"
	"time"
)

func main() {
	c := solaredge.Client{Token: os.Getenv("SOLAREDGE_APIKEY")}

	ctx := context.Background()
	end := time.Now()
	start := end.Add(-1 * 24 * time.Hour)

	sites, err := c.GetSites(ctx)
	if err != nil {
		panic(err)
	}

	for _, site := range sites {
		inventory, err := site.GetInventory(ctx)
		if err != nil {
			panic(err)
		}

		for _, inverter := range inventory.Inverters {
			telemetry, err := inverter.GetTelemetry(ctx, start, end)
			if err != nil {
				fmt.Println(err.Error())
				return
			}
			for _, entry := range telemetry {
				fmt.Printf("%s - %s - %5.1f V - %4.1f ºC - %6.1f\n", inverter.Name, entry.Time, entry.DcVoltage, entry.Temperature, entry.TotalActivePower)
			}
		}
	}
}

Output:

type InverterTelemetry added in v0.8.0 

type InverterTelemetry struct {
	L1Data struct {
		AcCurrent     float64 `json:"acCurrent"`
		AcFrequency   float64 `json:"acFrequency"`
		AcVoltage     float64 `json:"acVoltage"`
		ActivePower   float64 `json:"activePower"`
		ApparentPower float64 `json:"apparentPower"`
		CosPhi        float64 `json:"cosPhi"`
		ReactivePower float64 `json:"reactivePower"`
	} `json:"L1Data"`
	Time                  Time    `json:"date"`
	DcVoltage             float64 `json:"dcVoltage"`
	GroundFaultResistance float64 `json:"groundFaultResistance,omitempty"`
	InverterMode          string  `json:"inverterMode"`
	OperationMode         int     `json:"operationMode"`
	PowerLimit            float64 `json:"powerLimit"`
	Temperature           float64 `json:"temperature"`
	TotalActivePower      float64 `json:"totalActivePower"`
	TotalEnergy           float64 `json:"totalEnergy"`
}

InverterTelemetry contains technical data for an inverter.

type MeterEquipment added in v0.8.0 

type MeterEquipment struct {
	Name                       string `json:"name"`
	Manufacturer               string `json:"manufacturer"`
	Model                      string `json:"model"`
	FirmwareVersion            string `json:"firmwareVersion"`
	ConnectedSolarEdgeDeviceSN string `json:"connectedSolaredgeDeviceSN"`
	Type                       string `json:"type"`
	Form                       string `json:"form"`
}

MeterEquipment contains an meter's name, model, manufacturer, serial number, etc.

type MeterReadings added in v0.8.0 

type MeterReadings struct {
	Type   string  `json:"type"`
	Values []Value `json:"values"`
}

MeterReadings contains power measurements for a type of meter.

type ParseError added in v0.5.0 

type ParseError struct {
	Err  error
	Body []byte
}

ParseError wraps the error when failing to process the server response. Contains the original server response that generated the error, as well as the json error that triggered the error.

func (*ParseError) Error added in v0.5.0 

func (e *ParseError) Error() string

Error returns a string representation of a ParseError

func (*ParseError) Is added in v0.5.0 

func (e *ParseError) Is(e2 error) bool

Is returns true if e2 is a ParseError

func (*ParseError) Unwrap added in v0.5.0 

func (e *ParseError) Unwrap() error

Unwrap returns the wrapped error

type Power added in v0.8.0 

type Power struct {
	TimeUnit string  `json:"timeUnit"`
	Unit     string  `json:"unit"`
	Values   []Value `json:"values"`
}

Power is the site power measurements for a site over a period of time.

type PowerDetails added in v0.8.0 

type PowerDetails struct {
	Meters   []MeterReadings `json:"meters"`
	TimeUnit string          `json:"timeUnit"`
	Unit     string          `json:"unit"`
}

PowerDetails contains site power measurements from meters such as consumption, export (feed-in), import (purchase), etc.

type PowerFlowReading added in v0.8.0 

type PowerFlowReading struct {
	Status       string  `json:"status"`
	CurrentPower float64 `json:"currentPower"`
}

PowerFlowReading contains the current power flow for one element of the site.

type PowerOverview added in v0.8.0 

type PowerOverview struct {
	LastUpdateTime Time           `json:"lastUpdateTime"`
	LifeTimeData   EnergyOverview `json:"lifeTimeData"`
	LastYearData   EnergyOverview `json:"lastYearData"`
	LastMonthData  EnergyOverview `json:"lastMonthData"`
	LastDayData    EnergyOverview `json:"lastDayData"`
	CurrentPower   CurrentPower   `json:"currentPower"`
}

PowerOverview contains the energy produced at a site for its entire lifetime, current year, month and day (in Wh) and current power (in W).

type SensorEquipment added in v0.8.0 

type SensorEquipment struct {
	ConnectedSolarEdgeDeviceSN string `json:"connectedSolaredgeDeviceSN"`
	ID                         string `json:"id"`
	ConnectedTo                string `json:"connectedTo"`
	Category                   string `json:"category"`
	Type                       string `json:"type"`
}

SensorEquipment contains an sensor's name, model, manufacturer, serial number, etc.

type Site added in v0.8.0 

type Site struct {
	ID               int     `json:"id"`
	Name             string  `json:"name"`
	AccountID        int     `json:"accountId"`
	Status           string  `json:"status"`
	PeakPower        float64 `json:"peakPower"`
	LastUpdateTime   string  `json:"lastUpdateTime"`
	InstallationDate string  `json:"installationDate"`
	// TODO
	PtoDate  interface{} `json:"ptoDate"`
	Notes    string      `json:"notes"`
	Type     string      `json:"type"`
	Location struct {
		Address     string `json:"address"`
		Address2    string `json:"address2"`
		City        string `json:"city"`
		Zip         string `json:"zip"`
		Country     string `json:"country"`
		CountryCode string `json:"countryCode"`
		TimeZone    string `json:"timeZone"`
	} `json:"location"`
	PrimaryModule struct {
		ManufacturerName string  `json:"manufacturerName"`
		ModelName        string  `json:"modelName"`
		MaximumPower     float64 `json:"maximumPower"`
	} `json:"primaryModule"`
	PublicSettings struct {
		IsPublic bool `json:"isPublic"`
	} `json:"publicSettings"`
	Uris struct {
		SITEIMAGE  string `json:"SITE_IMAGE"`
		DATAPERIOD string `json:"DATA_PERIOD"`
		DETAILS    string `json:"DETAILS"`
		OVERVIEW   string `json:"OVERVIEW"`
	} `json:"uris"`
	// contains filtered or unexported fields
}

Site contains details for an installation registered under the supplied API Token

func (*Site) GetChangeLog added in v0.9.0 

func (s *Site) GetChangeLog(ctx context.Context, serialNr string) ([]ChangeLogEntry, error)

GetChangeLog returns a list of equipment component replacements, ordered by date. This method is applicable to inverters, optimizers, batteries and gateways.

func (*Site) GetDataPeriod added in v0.9.0 

func (s *Site) GetDataPeriod(ctx context.Context) (time.Time, time.Time, error)

GetDataPeriod returns the energy production start and end date for the active site.

Note: unlike the example in the specs, this only returns the date, not the time of day.

func (*Site) GetEnergy added in v0.9.0 

func (s *Site) GetEnergy(ctx context.Context, timeUnit string, start, end time.Time) (Energy, error)

GetEnergy returns the energy produced by the site for a given time range, with a given time resolution (timeUnit)

timeUnit must be one of the following values: QUARTER_OF_AN_HOUR, HOUR, DAY, WEEK, MONTH, YEAR.

The server limits the time range depending on the chosen timeUnit:

  • For QUARTER_OF_AN_HOUR and HOUR, the time range cannot exceed one month
  • For DAY, the time range cannot exceed one year.

If these conditions are not met, an APIError is returned.

func (*Site) GetEnergyDetails added in v0.9.0 

func (s *Site) GetEnergyDetails(ctx context.Context, timeUnit string, start, end time.Time) (EnergyDetails, error)

GetEnergyDetails returns site energy measurements from meters such as consumption, export (feed-in), import (purchase), etc. for a given time range and a specified time resolution.

timeUnit must be one of the following values: QUARTER_OF_AN_HOUR, HOUR, DAY, WEEK, MONTH, YEAR.

The server limits the time range depending on the chosen timeUnit:

  • For QUARTER_OF_AN_HOUR and HOUR, the time range cannot exceed one month
  • For DAY, the time range cannot exceed one year.

If these conditions are not met, an APIError is returned.

func (*Site) GetEnvBenefits added in v0.9.0 

func (s *Site) GetEnvBenefits(ctx context.Context) (EnvBenefits, error)

GetEnvBenefits returns all environmental benefits based on site energy production: gas emissions saved, equivalent trees planted and light bulbs powered for a day.

func (*Site) GetID added in v0.9.1 

func (s *Site) GetID() int

GetID returns the site's ID

func (*Site) GetInventory added in v0.9.0 

func (s *Site) GetInventory(ctx context.Context) (Inventory, error)

GetInventory returns the full inventory of SolarEdge equipment at the active site.

func (*Site) GetInverters added in v0.9.0 

func (s *Site) GetInverters(ctx context.Context) ([]Inverter, error)

GetInverters returns all inverters at the active site.

func (*Site) GetPower added in v0.9.0 

func (s *Site) GetPower(ctx context.Context, start, end time.Time) (Power, error)

GetPower returns the site power measurements in 15 minutes resolution.

Note: This API is limited to a one-month period. If the provided time range exceeds one month, an APIError is returned.

func (*Site) GetPowerDetails added in v0.9.0 

func (s *Site) GetPowerDetails(ctx context.Context, start, end time.Time) (PowerDetails, error)

GetPowerDetails returns site power measurements from meters such as consumption, export (feed-in), import (purchase), etc.

Note: This API is limited to one-month period. If the provided time range exceeds one month, an APIError is returned.

func (*Site) GetPowerFlow added in v0.9.0 

func (s *Site) GetPowerFlow(ctx context.Context) (CurrentPowerFlow, error)

GetPowerFlow returns the current power flow between all elements of the site including PV array, storage (battery), loads (consumption) and grid.

func (*Site) GetPowerOverview added in v0.9.0 

func (s *Site) GetPowerOverview(ctx context.Context) (PowerOverview, error)

GetPowerOverview returns the energy produced at the site for its entire lifetime, current year, month and day (in Wh) and current power (in W).

Example 
package main

import (
	"context"
	"fmt"
	"github.com/clambin/solaredge"
	"os"
)

func main() {
	ctx := context.Background()
	c := solaredge.Client{Token: os.Getenv("SOLAREDGE_APIKEY")}

	sites, err := c.GetSites(ctx)
	if err != nil {
		panic(err)
	}

	for _, site := range sites {
		overview, err := site.GetPowerOverview(ctx)
		if err != nil {
			panic(err)
		}

		fmt.Printf("Site: %s\nLast update: %s\nCurrent power: %.1fW", site.Name, overview.LastUpdateTime, overview.CurrentPower.Power)
	}
}

Output:

func (*Site) GetStorageData added in v0.9.0 

func (s *Site) GetStorageData(ctx context.Context, start, end time.Time) ([]Battery, error)

GetStorageData returns detailed information from batteries installed at the active site.

This API is limited to a one-week period. If the time range exceeds one week, an APIError is returned.

func (*Site) GetTimeFrameEnergy added in v0.9.0 

func (s *Site) GetTimeFrameEnergy(ctx context.Context, start, end time.Time) (TimeFrameEnergy, error)

GetTimeFrameEnergy returns the total energy produced for a given period.

Note: the period between end and start must not exceed one year. If it does, an APIError is returned.

type Sites added in v0.9.0 

type Sites []Site

Sites is a list of Site items.

func (Sites) FindByID added in v0.9.0 

func (s Sites) FindByID(id int) (Site, bool)

FindByID returns the Site with the specified ID. Returns false if the Site could not be found.

func (Sites) FindByName added in v0.9.0 

func (s Sites) FindByName(name string) (Site, bool)

FindByName returns the Site with the specified name. Returns false if the Site could not be found.

type Time added in v0.8.0 

type Time time.Time

Time represents a timestamp (YYYY-MM-DD HH:MI:SS) in the SolarEdge API.

func (Time) MarshalJSON added in v0.8.0 

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON marshals a Time into a JSON object

func (Time) String added in v0.8.0 

func (t Time) String() string

String returns a string representation of a Time. This is equivalent to time.Time{}.String()

func (*Time) UnmarshalJSON added in v0.8.0 

func (t *Time) UnmarshalJSON(bytes []byte) error

UnmarshalJSON unmarshals a timestamp in a JSON object to a Time

type TimeFrameEnergy added in v0.8.0 

type TimeFrameEnergy struct {
	Energy float64 `json:"energy"`
	Unit   string  `json:"unit"`
}

TimeFrameEnergy is the total energy produced for a given period.

type Value added in v0.8.0 

type Value struct {
	Date  Time    `json:"date"`
	Value float64 `json:"value,omitempty"`
}

Value is a common data type in the SolarEdge API. It represents a measurement at a moment in time.

Source Files

View all Source files

Directories

Path Synopsis
Package testutil is a supporting package for the solaredge package.
 Package testutil is a supporting package for the solaredge package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.