Skip to main content

Unofficial library for interacting with the Emporia Vue energy monitor.

Project description

PyEmVue

A Python Library for reading data from the Emporia Vue energy monitoring system.

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.

The backing API documentation can be accessed here

keys.json

{
    "username": "you@email.com",
    "password": "password"
}

Usage

Typical Example - Getting Recent Usage

This example prints out the device list and energy usage over the last minute.

#!/usr/bin/python3

import pyemvue
from pyemvue.enums import Scale, Unit

def print_recursive(usage_dict, info, depth=0):
    for gid, device in usage_dict.items():
        for channelnum, channel in device.channels.items():
            name = channel.name
            if name == 'Main':
                name = info[gid].device_name
            print('-'*depth, f'{gid} {channelnum} {name} {channel.usage} kwh')
            if channel.nested_devices:
                print_recursive(channel.nested_devices, info, depth+1)

vue = pyemvue.PyEmVue()
vue.login(username='put_username_here', password='put_password_here', token_storage_file='keys.json')

devices = vue.get_devices()
device_gids = []
device_info = {}
for device in devices:
    if not device.device_gid in device_gids:
        device_gids.append(device.device_gid)
        device_info[device.device_gid] = device
    else:
        device_info[device.device_gid].channels += device.channels

device_usage_dict = vue.get_device_list_usage(deviceGids=device_gids, instant=None, scale=Scale.MINUTE.value, unit=Unit.KWH.value)
print('device_gid channel_num name usage unit')
print_recursive(device_usage_dict, device_info)

This will print out something like:

device_gid channel_num name usage unit
 1234 1,2,3 Home 0.018625023078918456 kwh
- 2345 1,2,3 Furnace 0.0 kwh
- 2346 1,2,3 EV 0.0 kwh
 1234 1 Oven 0.0 kwh
 1234 2 Dryer 0.0 kwh
 1234 3 Water Heater 0.0 kwh
 1234 4 Kitchen 1 0.0 kwh
- 3456 1,2,3 Washer 2.0127220576742082e-06 kwh
 1234 5 Living Room 0.00031066492724719774 kwh
- 123456 1,2,3 myplug None kwh
- 123457 1,2,3 Tree None kwh
- 123458 1,2,3 Kitchen Counter 5.368702827258442e-05 kwh
 1234 6 Bar Area 0.0020457032945421006 kwh
 1234 7 Kitchen 2 0.0 kwh
 1234 8 Dishwasher 0.0002561144436730279 kwh
 1234 9 Bathroom Heater 0.0 kwh
 1234 10 Microwave 0.0 kwh
 1234 11 AC 0.0 kwh
 1234 12 Basement 0.0011743871887920825 kwh
- 123459 1,2,3 Dehumidifier 0.005342410305036585 kwh
 1234 13 Deck 0.0 kwh
 1234 14 Front Room 0.0027938466452995143 kwh
- 123450 1,2,3 Library 0.0001436362373061446 kwh
 1234 15 Office 0.004370743334687561 kwh
- 123451 1,2,3 Network 0.001209796911216301 kwh
- 123452 1,2,3 Bedroom Fan None kwh
 1234 16 Garage 0.0005456661001841227 kwh
 1234 Balance Balance 0.00037836666266123273 kwh

Log in with username/password

vue = PyEmVue()
vue.login(username='you@email.com', password='password', token_storage_file='keys.json')

token_storage_file is an optional file path where the access tokens will be written for reuse in later invocations. It will be updated whenever the tokens are automatically refreshed.

Log in with access tokens

with open('keys.json') as f:
    data = json.load(f)

vue = PyEmVue()
vue.login(id_token=data['id_token'],
    access_token=data['access_token'],
    refresh_token=data['refresh_token'],
    token_storage_file='keys.json')

Get customer details

vue = PyEmVue()
vue.login(id_token='id_token',
    access_token='access_token',
    refresh_token='refresh_token')

customer = vue.get_customer_details()

Returns a Customer object with email address, name, customer_gid, and creation date

Get devices

vue = PyEmVue()
vue.login(id_token='id_token',
    access_token='access_token',
    refresh_token='refresh_token')

vue.get_devices()

Returns a list of VueDevices with device information, including device_gid and list of VueDeviceChannels associated with the device. VueDeviceChannels are passed to other methods to get information for the specific channel.

Get additional device properties

vue = PyEmVue()
vue.login(id_token='id_token',
    access_token='access_token',
    refresh_token='refresh_token')

device1 = vue.get_devices()[0]
print(device1.device_name) # prints ""
device1 = vue.populate_device_properties(device1)
print(device1.device_name) # prints "Home"

Updates and returns the passed VueDevice with additional information about the device such as the device name (as set in the app), zip code, timezone, electricity costs, etc.

Arguments

  • device: A VueDevice as returned by get_devices. Will be updated and returned.

Get usages for devices

See Typical Example above.

Gets the usage for the given devices (specified by device_gid) over the provided time scale. May need to scale it manually to convert it to a rate, eg for 1 second data kilowatt={usage in kwh/s}*3600s/1h or for 1 minute data kilowatt={usage in kwh/m}*60m/1h.

Arguments

  • deviceGids: A list of device_gid values pulled from get_devices() or a single device_gid.
  • instant: What instant of time to check, will default to now if None.
  • scale: The time scale to check the usage over.
  • unit: The unit of measurement.

Get usage over time

vue = PyEmVue()
vue.login(id_token='id_token',
    access_token='access_token',
    refresh_token='refresh_token')

devices = vue.get_devices()

usage_over_time, start_time = vue.get_chart_usage(devices[0].channels[0], datetime.datetime.now(datetime.timezone.utc)-datetime.timedelta(days=7), datetime.datetime.now(datetime.timezone.utc), scale=Scale.DAY.value, unit=Unit.KWH.value)

print('Usage for the last seven days starting', start_time.isoformat())
for usage in usage_over_time:
    print(usage, 'kwh')

Gets the usage in the scale and unit provided over the given time range. Returns a tuple with the first element the usage list and the second the datetime that the range starts.

Arguments

  • channel: A VueDeviceChannel object, typically pulled from a VueDevice.
  • start: The start time for the time period. Defaults to now if None.
  • end: The end time for the time period. Default to now if None.
  • scale: The time scale to check the usage over.
  • unit: The unit of measurement.

Toggle outlets

vue = PyEmVue()
vue.login(id_token='id_token',
    access_token='access_token',
    refresh_token='refresh_token')

outlets = vue.get_outlets()
for outlet in outlets:
    vue.update_outlet(outlet, on=(not outlet.outlet_on))
    # alternatively it can be set on the outlet object first
    outlet.outlet_on = not outlet.outlet_on
    outlet = vue.update_outlet(outlet)

The get_outlets call returns a list of outlets directly but it is also possible to get a full VueDevice for the outlet first through the get_devices call and access an OutletDevice through the outlet attribute off of the VueDevice (ie device.outlet).

Toggle EV Charger (EVSE)

vue = PyEmVue()
vue.login(id_token='id_token',
    access_token='access_token',
    refresh_token='refresh_token')

chargers = vue.get_chargers()
for charger in chargers:
    vue.update_charger(outlet, on=(not charger.charger_on), charge_rate=charger.max_charging_rate)
    # alternatively you can update the charger object first
    charger.charger_on = not charger.charger_on
    charger.charging_rate = 6
    charger.max_charging_rate = 16
    charger = vue.update_charger(charger)

The get_chargers call returns a list of chargers directly but it is also possible to get a full VueDevice for the charger first through the get_devices call and access a ChargerDevice through the ev_charger attribute off of the VueDevice (ie device.ev_charger).

Get Vehicles and Status (including battery charge level).

Note: this call may take an extended amount of time depending on the vehicle, and may "wake" the vehicle to check status - be mindful of call volume, and aware of 10 second timeout that will hit if the vehicle doesn't reply in time (future may want to increase that).

vehicles = vue.get_vehicles()
print('List of Vehicles')
for vehicle in vehicles:
    print(f'\t{vehicle.vehicle_gid} ({vehicle.display_name}) - {vehicle.year} {vehicle.make} {vehicle.model}')

print('List of Vehicle Statuses')
for vehicle in vehicles:
    vehicleStatus = vue.get_vehicle_status(vehicle)
    print(f'\t{vehicleStatus.vehicle_gid} {vehicleStatus.vehicle_state} - Charging: {vehicleStatus.charging_state} Battery level: {vehicleStatus.battery_level}')

Disclaimer

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyemvue-0.18.9.tar.gz (27.4 kB view details)

Uploaded Source

Built Distribution

pyemvue-0.18.9-py3-none-any.whl (17.8 kB view details)

Uploaded Python 3

File details

Details for the file pyemvue-0.18.9.tar.gz.

File metadata

  • Download URL: pyemvue-0.18.9.tar.gz
  • Upload date:
  • Size: 27.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pyemvue-0.18.9.tar.gz
Algorithm Hash digest
SHA256 8879cd47a73f11d299ceab38cd0a1d7c467f14c8f58f42512a392dcaafc7d28d
MD5 9db5f127805224ce62a1fc7f54c404bc
BLAKE2b-256 a32ba375e1f332668c3bc029d5e6fd647e42f0a4329e91a6014090af4b48b380

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyemvue-0.18.9.tar.gz:

Publisher: publish-to-pypi.yml on magico13/PyEmVue

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyemvue-0.18.9-py3-none-any.whl.

File metadata

  • Download URL: pyemvue-0.18.9-py3-none-any.whl
  • Upload date:
  • Size: 17.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pyemvue-0.18.9-py3-none-any.whl
Algorithm Hash digest
SHA256 e61c1ad8ad0e501aa522866de08bcb455c83d240b2bfd9fa94b2387aceae3dd4
MD5 ddb6cd06dd8a808c964975a308f5fd81
BLAKE2b-256 0ff4dcdb7ec3f5c1fb37e8c0d94dd6eaf5bcbee7f363a81d548724de69360a2a

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyemvue-0.18.9-py3-none-any.whl:

Publisher: publish-to-pypi.yml on magico13/PyEmVue

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page