Add ENTSO-E "Day Ahead Pricing" tariff provider (evcc-io#9794)

Author: duckfullstop

tariff/entsoe.go

@@ -0,0 +1,183 @@
+package tariff
+
+import (
+	"bytes"
+	"encoding/xml"
+	"errors"
+	"net/http"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/cenkalti/backoff/v4"
+	"github.com/evcc-io/evcc/api"
+	"github.com/evcc-io/evcc/tariff/entsoe"
+	"github.com/evcc-io/evcc/util"
+	"github.com/evcc-io/evcc/util/request"
+	"github.com/evcc-io/evcc/util/transport"
+)
+
+type Entsoe struct {
+	*request.Helper
+	*embed
+	mux     sync.Mutex
+	log     *util.Logger
+	token   string
+	domain  string
+	data    api.Rates
+	updated time.Time
+}
+
+var _ api.Tariff = (*Entsoe)(nil)
+
+func init() {
+	registry.Add("entsoe", NewEntsoeFromConfig)
+}
+
+func NewEntsoeFromConfig(other map[string]interface{}) (api.Tariff, error) {
+	var cc struct {
+		embed         `mapstructure:",squash"`
+		Securitytoken string
+		Domain        string
+	}
+
+	if err := util.DecodeOther(other, &cc); err != nil {
+		return nil, err
+	}
+
+	if cc.Securitytoken == "" {
+		return nil, errors.New("securitytoken must be defined")
+	}
+
+	domain, err := entsoe.Area(entsoe.BZN, strings.ToUpper(cc.Domain))
+	if err != nil {
+		return nil, err
+	}
+
+	log := util.NewLogger("entsoe").Redact(cc.Securitytoken)
+
+	t := &Entsoe{
+		log:    log,
+		Helper: request.NewHelper(log),
+		embed:  &cc.embed,
+		token:  cc.Securitytoken,
+		domain: domain,
+	}
+
+	// Wrap the client with a decorator that adds the security token to each request.
+	t.Client.Transport = &transport.Decorator{
+		Base: t.Client.Transport,
+		Decorator: transport.DecorateQuery(map[string]string{
+			"securityToken": cc.Securitytoken,
+		}),
+	}
+
+	done := make(chan error)
+	go t.run(done)
+	err = <-done
+
+	return t, err
+}
+
+func (t *Entsoe) run(done chan error) {
+	var once sync.Once
+
+	bo := newBackoff()
+
+	// Data updated by ESO every half hour, but we only need data every hour to stay current.
+	for ; true; <-time.Tick(time.Hour) {
+		var tr entsoe.PublicationMarketDocument
+
+		if err := backoff.Retry(func() error {
+			// Request the next 24 hours of data.
+			data, err := t.DoBody(entsoe.DayAheadPricesRequest(t.domain, time.Hour*24))
+
+			// Consider whether errors.As would be more appropriate if this needs to start dealing with wrapped errors.
+			if se, ok := err.(request.StatusError); ok {
+				if se.HasStatus(http.StatusBadRequest) {
+					return backoff.Permanent(se)
+				}
+
+				return se
+			}
+
+			var doc entsoe.Document
+			if err := xml.NewDecoder(bytes.NewReader(data)).Decode(&doc); err != nil {
+				return backoff.Permanent(err)
+			}
+
+			switch doc.XMLName.Local {
+			case entsoe.AcknowledgementMarketDocumentName:
+				var doc entsoe.AcknowledgementMarketDocument
+				if err := xml.NewDecoder(bytes.NewReader(data)).Decode(&doc); err != nil {
+					return backoff.Permanent(err)
+				}
+
+				return backoff.Permanent(errors.New(doc.Reason.Text))
+
+			case entsoe.PublicationMarketDocumentName:
+				if err := xml.NewDecoder(bytes.NewReader(data)).Decode(&tr); err != nil {
+					return backoff.Permanent(err)
+				}
+
+				if tr.Type != string(entsoe.ProcessTypeDayAhead) {
+					return backoff.Permanent(errors.New("invalid document type: " + tr.Type))
+				}
+
+				return nil
+
+			default:
+				return backoff.Permanent(errors.New("invalid document name: " + doc.XMLName.Local))
+			}
+		}, bo); err != nil {
+			once.Do(func() { done <- err })
+
+			t.log.ERROR.Println(err)
+			continue
+		}
+
+		if len(tr.TimeSeries) == 0 {
+			once.Do(func() { done <- entsoe.ErrInvalidData })
+			t.log.ERROR.Println(entsoe.ErrInvalidData)
+			continue
+		}
+
+		// extract desired series
+		tsdata, err := entsoe.GetTsPriceData(tr.TimeSeries, entsoe.ResolutionHour)
+		if err != nil {
+			once.Do(func() { done <- err })
+			t.log.ERROR.Println(err)
+			continue
+		}
+
+		once.Do(func() { close(done) })
+
+		t.mux.Lock()
+		t.updated = time.Now()
+
+		t.data = make(api.Rates, 0, len(tsdata))
+		for _, r := range tsdata {
+			ar := api.Rate{
+				Start: r.ValidityStart,
+				End:   r.ValidityEnd,
+				Price: t.totalPrice(r.Value),
+			}
+			t.data = append(t.data, ar)
+		}
+
+		t.mux.Unlock()
+	}
+}
+
+// Rates implements the api.Tariff interface
+func (t *Entsoe) Rates() (api.Rates, error) {
+	t.mux.Lock()
+	defer t.mux.Unlock()
+	return slices.Clone(t.data), outdatedError(t.updated, time.Hour)
+}
+
+// Type implements the api.Tariff interface
+func (t *Entsoe) Type() api.TariffType {
+	return api.TariffTypePriceDynamic
+}

tariff/entsoe/api.go

@@ -0,0 +1,119 @@
+// Package entsoe implements a minimalized version of the European Network of Transmission System Operators for Electricity's
+// Transparency Platform API (https://transparency.entsoe.eu)
+package entsoe
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"sort"
+	"time"
+
+	"github.com/dylanmei/iso8601"
+	"github.com/evcc-io/evcc/util/request"
+)
+
+const (
+	// BaseURI is the root path that the API is accessed from.
+	BaseURI = "https://web-api.tp.entsoe.eu/api"
+
+	// numericDateFormat is a time.Parse compliant formatting string for the numeric date format used by entsoe get requests.
+	numericDateFormat = "200601021504"
+)
+
+var ErrInvalidData = errors.New("invalid data received")
+
+// DayAheadPricesRequest constructs a new DayAheadPricesRequest.
+func DayAheadPricesRequest(domain string, duration time.Duration) *http.Request {
+	now := time.Now().Truncate(time.Hour)
+
+	params := url.Values{
+		"DocumentType": {string(ProcessTypeDayAhead)},
+		"In_Domain":    {domain},
+		"Out_Domain":   {domain},
+		"PeriodStart":  {now.Format(numericDateFormat)},
+		"PeriodEnd":    {now.Add(duration).Format(numericDateFormat)},
+	}
+
+	uri := BaseURI + "?" + params.Encode()
+	req, _ := request.New(http.MethodGet, uri, nil, request.AcceptXML)
+
+	return req
+}
+
+// RateData defines the per-unit Value over a period of time spanning ValidityStart and ValidityEnd.
+type RateData struct {
+	ValidityStart time.Time
+	ValidityEnd   time.Time
+	Value         float64
+}
+
+// GetTsPriceData accepts a set of TimeSeries data entries, and
+// returns a sorted array of RateData based on the timestamp of each data entry.
+func GetTsPriceData(ts []TimeSeries, resolution ResolutionType) ([]RateData, error) {
+	for _, v := range ts {
+		if v.Period.Resolution != resolution {
+			continue
+		}
+
+		data, err := ExtractTsPriceData(&v)
+		if err != nil {
+			return nil, err
+		}
+
+		// Now sort all entries by timestamp.
+		// Not sure if this is entirely necessary for evcc's use, could consider removing this if it becomes a performance issue.
+		sort.Slice(data, func(i, j int) bool {
+			return data[i].ValidityStart.Before(data[j].ValidityStart)
+		})
+
+		return data, nil
+	}
+
+	return nil, fmt.Errorf("no data for resolution: %v", resolution)
+}
+
+// ExtractTsPriceData massages the given TimeSeries data set to provide RateData entries with associated start and end timestamps.
+func ExtractTsPriceData(timeseries *TimeSeries) ([]RateData, error) {
+	data := make([]RateData, 0, len(timeseries.Period.Point))
+
+	duration, err := iso8601.ParseDuration(string(timeseries.Period.Resolution))
+	if err != nil {
+		return nil, err
+	}
+
+	// tCurrencyUnit := timeseries.CurrencyUnitName
+	// tPriceMeasureUnit := timeseries.PriceMeasureUnitName
+	// Brief check just to make sure we're about to decode the data as expected.
+	if timeseries.PriceMeasureUnitName != "MWH" {
+		return nil, fmt.Errorf("%w: price data not in expected unit", ErrInvalidData)
+	}
+
+	tPointer := timeseries.Period.TimeInterval.Start.Time
+	for _, point := range timeseries.Period.Point {
+		d := RateData{
+			Value:         point.PriceAmount / 1e3, // Price/MWh to Price/kWh
+			ValidityStart: tPointer,
+		}
+
+		// Nudge pointer on as required by defined data resolution
+		switch timeseries.Period.Resolution {
+		case ResolutionQuarterHour, ResolutionHalfHour, ResolutionHour:
+			tPointer = tPointer.Add(duration)
+		case ResolutionDay:
+			tPointer = tPointer.AddDate(0, 0, 1)
+		case ResolutionWeek:
+			tPointer = tPointer.AddDate(0, 0, 7)
+		case ResolutionYear:
+			tPointer = tPointer.AddDate(0, 1, 0)
+		default:
+			return nil, fmt.Errorf("invalid resolution: %v", timeseries.Period.Resolution)
+		}
+		d.ValidityEnd = tPointer
+
+		data = append(data, d)
+	}
+
+	return data, nil
+}