emporia

README

emporia-api-go

emporia-api-go is Go API Client for the Emporia Vue energy monitoring system API. This API is not officially supported by Emporia.

The library can be invoked directly to pull back some basic info but requires your email and password to be added to a keys.json file, which is then replaced with the access tokens.

Mike Marvin's API documentation can help to understand the underlaying API, or use the OpenAPI file in the /docs directory to understand the API.

Installation

go get -u github.com/cnovak/emporia

Usage

You need a username and password to initialize the client:

package main

import (
	"fmt"
	"os"

	emporia "github.com/cnovak/emporia"
)

func main() {
	username := os.Getenv("EMPORIA_USERNAME")
	password := os.Getenv("EMPORIA_PASSWORD")

	client, err := emporia.NewClient(username, password)
	if err != nil {
		panic(err)
	}

	devices, err := client.GetDevices()
	if err != nil {
		panic(err)
	}
	fmt.Printf("============== \nDevices:\n============== \n%+v\n\n", devices)

}

Credits

Thanks to Mike Marvin for his work in the PyEmVue project documenting the Emporia Energy API.

Disclaimer

This project is not affiliated with or endorsed by Emporia Energy.

Documentation

Index

• Variables
• func SplitToString(a []uint64, sep string) string
• type Channel
• type ChannelType
• type ChannelUsage
• type ChannelUsageType
  • func (c ChannelUsageType) String() string
• type Client
  • func NewClient(username string, password string) (*Client, error)
  • func (c *Client) Authenticate(username string, password string) error
  • func (c *Client) GetDeviceListUsages(deviceGids []uint64, scale Scale, energyUnit EnergyUnit, instant time.Time) (*DeviceListUsages, error)
  • func (c *Client) GetDevices() (*DeviceResponse, error)
  • func (c *Client) GetSolar() (*[]Device, error)
• type Device
• type DeviceListUsages
• type DeviceResponse
• type DeviceUsage
• type EnergyUnit
  • func ParseEnergyUnit(s string) (EnergyUnit, error)
  • func (e EnergyUnit) String() string
  • func (e *EnergyUnit) UnmarshalJSON(byte []byte) error
• type LatitudeLongitude
• type LocationInformation
• type LocationProperty
• type Scale
  • func ParseScale(s string) (Scale, error)
  • func (i Scale) String() string
  • func (s *Scale) UnmarshalJSON(byte []byte) error

Examples

• NewClient

Variables

var ChannelTypeLookup = map[string]ChannelType{
	"Air Conditioner":          AirConditioner,
	"Battery":                  Battery,
	"Boiler":                   Boiler,
	"Clothes Dryer":            ClothesDryer,
	"Clothes Washer":           ClothesWasher,
	"Computer/Network":         Computer,
	"Cooktop/Range/Oven/Stove": Cooktop,
	"Dishwasher":               Dishwasher,
	"Electric Vehicle/RV":      ElectricVehicle,
	"Fridge/Freezer":           Fridge,
	"Furnace":                  Furnace,
	"Garage/Shop/Barn/Shed":    Garage,
	"Solar/Generation":         Solar,
	"Hot Tub/Spa":              HotTub,
	"Humidifier/Dehumidifier":  Humidifier,
	"Kitchen":                  Kitchen,
	"Microwave":                Microwave,
	"Other":                    Other,
	"Pump":                     Pump,
	"Room/Multi-use Circuit":   Room,
	"Sub Panel":                SubPanel,
	"Water Heater":             WaterHeater,
	"Heat Pump":                HeatPump,
	"Lights":                   Lights,
}

Functions

func SplitToString

func SplitToString(a []uint64, sep string) string

Types

type Channel

type Channel struct {
	DeviceGID         int     `json:"deviceGid"`
	Name              string  `json:"name"`
	ChannelNum        string  `json:"channelNum"`
	ChannelMultiplier float64 `json:"channelMultiplier"`
	ChannelTypeGID    int     `json:"channelTypeGid"`
}

type ChannelType

type ChannelType uint8

const (
	AirConditioner  ChannelType = 1
	Battery         ChannelType = 2
	Boiler          ChannelType = 3
	ClothesDryer    ChannelType = 4
	ClothesWasher   ChannelType = 5
	Computer        ChannelType = 6
	Cooktop         ChannelType = 7
	Dishwasher      ChannelType = 8
	ElectricVehicle ChannelType = 9
	Fridge          ChannelType = 10
	Furnace         ChannelType = 11
	Garage          ChannelType = 12
	Solar           ChannelType = 13
	HotTub          ChannelType = 14
	Humidifier      ChannelType = 15
	Kitchen         ChannelType = 16
	Microwave       ChannelType = 17
	Other           ChannelType = 18
	Pump            ChannelType = 19
	Room            ChannelType = 20
	SubPanel        ChannelType = 21
	WaterHeater     ChannelType = 22
	HeatPump        ChannelType = 24
	Lights          ChannelType = 26
)

type ChannelUsage

type ChannelUsage struct {
	Name          string        `json:"name"`
	Percentage    float64       `json:"percentage"`
	NestedDevices []DeviceUsage `json:"nestedDevices"`
	Usage         float64       `json:"usage"`
	DeviceGid     uint64        `json:"deviceGid"`
	ChannelNum    string        `json:"channelNum"`
}

type ChannelUsageType

type ChannelUsageType uint8

Special channels in the device usage response

const (
	NetUsage ChannelUsageType = iota
	TotalUsage
	Balance
)

func (ChannelUsageType) String

func (c ChannelUsageType) String() string

type Client

type Client struct {
	AccessToken  string
	IDToken      string
	RefreshToken string
	// contains filtered or unexported fields
}

Client represents an Emporia API Client

func NewClient

func NewClient(username string, password string) (*Client, error)

Example

username := os.Getenv("EMPORIA_USERNAME")
password := os.Getenv("EMPORIA_PASSWORD")

client, err := NewClient(username, password)
if err != nil {
	panic(err)
}

devices, err := client.GetDevices()
if err != nil {
	panic(err)
}
fmt.Printf("Devices:\n%+v\n\n", devices)

func (*Client) Authenticate

func (c *Client) Authenticate(username string, password string) error

func (*Client) GetDeviceListUsages

func (c *Client) GetDeviceListUsages(deviceGids []uint64, scale Scale, energyUnit EnergyUnit, instant time.Time) (*DeviceListUsages, error)

GetDeviceListUsages returns usage data for a list of devices

func (*Client) GetDevices

func (c *Client) GetDevices() (*DeviceResponse, error)

func (*Client) GetSolar

func (c *Client) GetSolar() (*[]Device, error)

type Device

type Device struct {
	DeviceGID            uint64           `json:"deviceGid"`
	ManufacturerDeviceID string           `json:"manufacturerDeviceId"`
	Model                string           `json:"model"`
	Firmware             string           `json:"firmware"`
	Channels             []Channel        `json:"channels"`
	Devices              []Device         `json:"devices"`
	LocationProperties   LocationProperty `json:"locationProperties"`
}

type DeviceListUsages

type DeviceListUsages struct {
	Devices    []DeviceUsage `json:"devices"`
	EnergyUnit EnergyUnit    `json:"energyUnit"`
	Instant    time.Time     `json:"instant"`
	Scale      Scale         `json:"scale"`
}

type DeviceResponse

type DeviceResponse struct {
	CustomerGID int      `json:"customerGid"`
	Email       string   `json:"email"`
	FirstName   string   `json:"firstName"`
	LastName    string   `json:"lastName"`
	CreatedAt   string   `json:"createdAt"`
	Devices     []Device `json:"devices"`
}

type DeviceUsage

type DeviceUsage struct {
	ChannelUsages []ChannelUsage `json:"channelUsages"`
	DeviceGid     uint64         `json:"deviceGid"`
}

type EnergyUnit

type EnergyUnit uint8

Enum for EnergyUnit to be sent to GetDeviceListUsages

const (
	KilowattHours EnergyUnit = iota
	Dollars
	AmpHours
	Trees
	GallonsOfGas
	MilesDriven
	CarbonEnergyUnit
)

Valid EnergyUnit values

func ParseEnergyUnit

func ParseEnergyUnit(s string) (EnergyUnit, error)

func (EnergyUnit) String

func (e EnergyUnit) String() string

func (*EnergyUnit) UnmarshalJSON

func (e *EnergyUnit) UnmarshalJSON(byte []byte) error

type LatitudeLongitude

type LatitudeLongitude struct {
	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`
}

type LocationInformation

type LocationInformation struct {
	AirConditioning bool   `json:"airConditioning"`
	HeatSource      string `json:"heatSource"`
	LocationSqFt    string `json:"locationSqFt"`
	NumElectricCars string `json:"numElectricCars"`
	LocationType    string `json:"locationType"`
	NumPeople       string `json:"numPeople"`
	SwimmingPool    bool   `json:"swimmingPool"`
	HotTub          bool   `json:"hotTub"`
}

type LocationProperty

type LocationProperty struct {
	DeviceGID             uint64              `json:"deviceGid"`
	DeviceName            string              `json:"deviceName"`
	ZipCode               string              `json:"zipCode"`
	TimeZone              string              `json:"timeZone"`
	BillingCycleStartDay  int                 `json:"billingCycleStartDay"`
	UsageCentPerKwHour    float64             `json:"usageCentPerKwHour"`
	PeakDemandDollarPerKw float64             `json:"peakDemandDollarPerKw"`
	LocationInformation   LocationInformation `json:"locationInformation"`
	LatitudeLongitude     LatitudeLongitude   `json:"latitudeLongitude"`
}

type Scale

type Scale int

Enum for Scale to be sent to GetDeviceListUsages

const (
	Second Scale = iota
	Minute
	Hour
	Day
	Week
	Month
	Year
)

Valid Instant values

func ParseScale

func ParseScale(s string) (Scale, error)

func (Scale) String

func (i Scale) String() string

Format Scale into string the API expects

func (*Scale) UnmarshalJSON

func (s *Scale) UnmarshalJSON(byte []byte) error