powerpal

README

Client for the Powerpal Readings API

https://readings.powerpal.net (https://www.powerpal.net)

Device

The Powerpal is a small Bluetooth Low Energy (BLE) device that reads the flashes of the LED on a smart electricity meter and allows for a realtime view of power consumption in the home.

App

The Powerpal mobile app, when paired with a Powerpal device:

• displays current and historic power consumption
• includes challenges and advice
• forwards meter readings to the cloud; and
• can provide a signed download link for up to 90 days of usage history

The Missing Link

It is currently not possible for a Powerpal end user to view their usage data outside of the app without manually creating an export link for each 90 day period, then loading the provided CSV data into a visualisation tool of their choice.

This repo was created to allow for regular retrieval of the latest uploaded readings so they can be loaded into a local DB for:

• long term storage
• visualization on a private home dashboard
• triggering home automation actions

More Info

See: https://forfuncsake.github.io/post/2021/08/owning-my-own-powerpal-data/

The author of this repo is not affiliated with Powerpal.

Documentation

Overview

Package powerpal provides a basic client for retrieving meter readings from the Powerpal readings API for a given device with its authorization token. API: https://readings.powerpal.net/documentation

Index

• Constants
• type CSVExporter
  • func NewCSVExporter(w io.Writer, writeHeader bool, allFields bool) *CSVExporter
  • func (e *CSVExporter) Write(readings []MeterReading) error
• type Client
  • func NewClient(addr string, serial string, token string) *Client
  • func (c *Client) FetchReadings(since time.Time) ([]MeterReading, error)
• type Device
• type Exporter
• type InfluxExporter
  • func NewInfluxExporter(c influxdb2.Client, org string, bucket string, measurement string) *InfluxExporter
  • func (e *InfluxExporter) Write(readings []MeterReading) error
• type MeterReading

Constants

const (
	// Powerpal docs note that the meter_readings API is
	// limited to batchd of 50k records at a time.
	BatchSize = 50000

	// Time series data is stored/returned in 60s intervals.
	SecondsPerReading = 60
)

Types

type CSVExporter

type CSVExporter struct {
	// contains filtered or unexported fields
}

func NewCSVExporter

func NewCSVExporter(w io.Writer, writeHeader bool, allFields bool) *CSVExporter

NewCSVExporter returns an exporter configured to write csv data. It can be configured to write or omit (when appending) a header row; and to emit the same fields as the powerpal app CSV export (datetime_utc,watt_hours,cost_dollars,is_peak), or all fields.

func (*CSVExporter) Write

func (e *CSVExporter) Write(readings []MeterReading) error

Write implements the Exporter interface for CSV output.

type Client

type Client struct {
	// contains filtered or unexported fields
}

A Client provides methods to query the Powerpal API server.

func NewClient

func NewClient(addr string, serial string, token string) *Client

NewClient creates a Powerpal API client.

func (*Client) FetchReadings

func (c *Client) FetchReadings(since time.Time) ([]MeterReading, error)

FetchReadings will fetch all meter readings from the Powerpal API since (and including) the provided timestamp.

type Device

type Device struct {
	AvailableDays  int     `json:"available_days"`
	FirstTimestamp int64   `json:"first_reading_timestamp"`
	LastCost       float64 `json:"last_reading_cost"`
	LastTimestamp  int64   `json:"last_reading_timestamp"`
	LastWattHours  int     `json:"last_reading_watt_hours"`
	Serial         string  `json:"serial_number"`
	TotalCost      float64 `json:"total_cost"`
	TotalReads     int     `json:"total_meter_reading_count"`
	TotalWattHours int     `json:"total_watt_hours"`
}

Device represents the data returned from the readings API device endpoint. It is used to determine timestamps for meter_reading data availability.

type Exporter

type Exporter interface {
	Write([]MeterReading) error
}

type InfluxExporter

type InfluxExporter struct {
	// contains filtered or unexported fields
}

func NewInfluxExporter

func NewInfluxExporter(c influxdb2.Client, org string, bucket string, measurement string) *InfluxExporter

NewInfluxExporter returns an exporter configured to write results to InfluxDB.

func (*InfluxExporter) Write

func (e *InfluxExporter) Write(readings []MeterReading) error

Write implements the Exporter interface for InfluxDB output.

type MeterReading

type MeterReading struct {
	Cost      float64 `json:"cost"`
	Peak      bool    `json:"is_peak"`
	Pulses    int     `json:"pulses"`
	Samples   int     `json:"samples"`
	Timestamp int64   `json:"timestamp"`
	WattHours int     `json:"watt_hours"`
}

A MeterReading provides a single interval meter reading snapshot.