Skip to main content

pyDuke-Energy

PyPi Project GitHub Build GitHub Activity License

Project Maintenance GitHub Top Language Black

Python3 wrapper for the unofficial Duke Energy API.

Designed to work with Home Assistant. Unlikely to ever be fully implemented. The primary goal is to expose Duke Energy Gateway usage information.

The library supports access to the real-time power usage implemented via an MQTT over websockets connection, or a more traditional REST API to poll near-real-time data.

IMPORTANT - Deprecation Warning

Duke Energy is shutting down the Gateway pilot program at the end of June. This library will stop functioning and will be deprecated.

Before You Begin

Disclaimer

The API is unofficial, not documented, and probably not supposed to be used by third-parties. It is only accessible as it powers the Duke Energy phone app and we can mimic the app requests.

In addition, the Gateway functionality is part of a pilot program. There is no guarantee on availability going forward.

With that said, please see this disclaimer: This library could stop working at any time. Some functionality may be removed from the API entirely. Duke Energy may even request we stop hitting this API.

Along those same lines, please do not abuse their API.

Gateway Requirement

In order to call the gateway related functions, including getting energy usage, you will need to have a Duke Energy Gateway. This is currently available via a pilot program.

It is possible to query yesterday's energy usage without a gateway; however, I have not implemented that as I did not find it useful.

Limitations

Some limitations I've identified:

  • Non-real-time Energy usage data is down to the minute, but is only updated once every 15 minutes. Meaning, the last 15 minutes of minute-by-minute data will all arrive at once after 15 minutes. My best guess is that the gateway only sends data to Duke Energy every 15 minutes. This is a limitation in the app as well.

Usage

Installation

The latest version is available on PyPi.

pip install pyduke-energy

Examples

Various usage examples can be found in the examples/ folder of this repo.

Example REST API Usage

The quick example below shows how to retrieve non-real-time usage info using the traditional REST API.

async with aiohttp.ClientSession() as client:
    duke_energy = DukeEnergyClient(email, password, client)
    await duke_energy.select_default_meter() # NB: can also use MeterInfo from API with select_meter()
    usage = await duke_energy.get_gateway_usage(datetime.date(2021, 1, 1), datetime.date(2021, 1, 2))

A more detailed example is in examples/example_rest.py.

Example Real-time Usage

Real-time usage can be retrieved using an MQTT connection. The quick example below shows how to do this using the default real-time client.

async with aiohttp.ClientSession() as client:
    duke_energy = DukeEnergyClient(email, password, client)
    duke_rt = DukeEnergyRealtime(duke_energy)
    await duke_rt.select_default_meter()
    await duke_rt.connect_and_subscribe_forever()

More detailed examples can be found in examples/example_realtime.py and examples/example_realtime_kafka.py.

Running Examples

If you want to run the examples, you will need to install extra dependencies.

pip install .[example]
python examples/example_rest.py

Development

Environment Setup

Dev Container

The preferred method of development is using the Visual Studio Code devcontainer, which will handle setting up your environment including all dependencies.

  1. Open repo in VS Code (e.g. code . from repo root)
  2. Re-open in container when the pop-up appears in VS Code
  3. Wait for the container to build
  4. Done!

Manual Installation

You can also develop outside of a dev container if desired. The example below uses a virtualenv which is optional but recommended.

virtualenv venv
source venv/bin/activate
pip install -e .[example,tests]

Testing

The test command will run the test suite and also run linting against all source files.

tox

To run just the tests:

tox -e py310

To run just the linting:

tox -e lint

Android App Debugging

If you want to debug requests via the Android app, the following general approach works well for me.

  1. Install HTTP Toolkit on your computer.
  2. Set up Android Studio so that you can use an emulator through it.
  3. Start Android Studio emulator and use HTTP Toolkit to connect to it via ADB. Make sure to set up the HTTPS request intercepting.
  4. Install Duke Energy APK on the emulator. You can download an xapk file from a site like APKPure. To install an xapk file on an emulator, extract the xapk file using something like WinRAR and drag the inside apk file to the emulator.
  5. Start Duke Energy app on the emulator and logs should now be requested in your HTTP Toolkit app.

Metadata

Release files for pyduke-energy 1.0.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyduke-energy 1.0.6
File Size Uploaded Provenance Actions
pyduke-energy-1.0.6.tar.gz 18.2 kB Without provenance Details for pyduke-energy-1.0.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyduke-energy 1.0.6
File Interpreter ABI Platform Actions
pyduke_energy-1.0.6-py3-none-any.whl Python 3 none any Details for pyduke_energy-1.0.6-py3-none-any.whl

Total release size: 34.9 kB

Release files / pyduke-energy-1.0.6.tar.gz

Download URL pyduke-energy-1.0.6.tar.gz
Size 18.2 kB
Tags Source
SHA-256 checksum
How to use checksums
a4c91eb29fe80b2997eb53b44552260bf23d45001b80de51c86d87506b0c772d
BLAKE2b-256 checksum
How to use checksums
07804574d62e7beb5a7f9c61e7e3d014b6420839ca4716d83de51ebf3a817fb1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.10.9

Release files / pyduke_energy-1.0.6-py3-none-any.whl

Download URL pyduke_energy-1.0.6-py3-none-any.whl
Size 16.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
29d78a345c7838b0edc8226ce63cc6b9414a277f2fd01fa9b731c96e5f05e24e
BLAKE2b-256 checksum
How to use checksums
b276dab27ddd83ecdac52913542cd11b46d549e47f8367fd6ec152c6b8fae32f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.2 CPython/3.10.9

Security for pyduke-energy 1.0.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page