emporia-energy_skill

Overview

This skill provides direct querying of Emporia Vue energy data using either the Emporia cloud (PyEmVue) or a local ESPHome API. It includes guidance to choose and configure cloud vs esphome modes and simple commands to list devices, show a summary, or inspect a specific circuit. Outputs are JSON and intended for downstream automation or logging.

How this skill works

Set EMPORIA_MODE to either cloud or esphome and provide the required environment variables for that mode. The cloud path uses PyEmVue and Emporia account credentials to fetch data from the Emporia cloud. The esphome path connects to a locally flashed ESPHome node over its native API (port 6053 by default). Scripts produce a JSON payload with timestamp, units, totals, top circuits, and channels used.

When to use it

• When you need automated access to Emporia Vue metrics for dashboards, scripts, or alerts.
• When the device is still on stock firmware and you prefer cloud convenience.
• When the device is flashed with ESPHome and you require local LAN access without cloud dependency.
• To quickly audit available channels before integrating with other systems.
• When you need JSON-formatted energy summaries for ingest into monitoring pipelines.

Best practices

• Start with the list command to confirm channel names and indexing before querying circuits.
• Use cloud mode if you are unsure whether the device is ESPHome-flashed; it requires only account credentials.
• Use esphome mode only for devices you have flashed and that are reachable on your LAN.
• Keep secrets out of logs and never print EMPORIA_PASSWORD, ESPHOME_API_KEY, or similar values.
• Use virtual environments and the provided requirements files to avoid dependency conflicts.

Example use cases

• Run summary in cloud mode to collect per-minute energy metrics for a remote installation.
• Query circuit <name> via ESPHome to get a local, low-latency reading from a specific sensor.
• Automate a nightly script that calls list to detect changes in channel configuration.
• Feed the JSON summary into a home automation platform or time-series database for visualization.
• Switch between cloud and local modes depending on network availability or privacy requirements.