Introduction
# Emporia Energy Skill
Use the scripts in `{baseDir}/scripts` to query Emporia Vue data directly.
Modes are selected with `EMPORIA_MODE`: - `cloud`: Emporia cloud API via PyEmVue (like the Home Assistant integration) - `esphome`: Local ESPHome API (for flashed devices)
## Choose a mode (cloud vs local)
- Use **cloud** if your Emporia device is still on stock firmware or you want the simplest setup. Requires Emporia account credentials and internet access. - Use **esphome** only if the device is flashed with ESPHome and on your LAN. Requires the device IP/hostname and native API access on port 6053.
If you are unsure whether the device is ESPHome-flashed, choose cloud mode.
## Environment
### Cloud mode - `EMPORIA_EMAIL` - `EMPORIA_PASSWORD`
Optional: - `EMPORIA_SCALE` (`MINUTE`, `SECOND`, `MINUTES_15`, `DAY`, `MONTH`) - defaults to `MINUTE`
### ESPHome mode - `ESPHOME_HOST` - `ESPHOME_PORT` (optional, default `6053`) - `ESPHOME_API_KEY` (Noise PSK, base64) or `ESPHOME_PASSWORD` (legacy)
## Configuration steps
Cloud: 1. Set `EMPORIA_MODE=cloud`. 2. Set `EMPORIA_EMAIL` and `EMPORIA_PASSWORD`. 3. (Optional) Set `EMPORIA_SCALE` to control power vs energy units. 4. Run `list` first to confirm channels, then `summary` or `circuit <name>`.
ESPHome: 1. Ensure the device is flashed with ESPHome and on your LAN. 2. Set `EMPORIA_MODE=esphome`. 3. Set `ESPHOME_HOST` to the device IP/hostname (not Home Assistant). 4. If the ESPHome node uses encryption, set `ESPHOME_API_KEY` (base64 Noise PSK). 5. Run `list` first to confirm channels, then `summary` or `circuit <name>`.
## Commands
The scripts accept: - `summary` (default) - `list` - `circuit <name>`
## Usage
Cloud: ``` export EMPORIA_MODE=cloud export EMPORIA_EMAIL="[email protected]" export EMPORIA_PASSWORD="..." python {baseDir}/scripts/emporia_cloud.py summary ```
ESPHome: ``` export EMPORIA_MODE=esphome export ESPHOME_HOST="192.168.1.50" export ESPHOME_API_KEY="base64-noise-psk" python {baseDir}/scripts/emporia_esphome.py summary ```
## Dependencies (pip by default)
Cloud: ``` python3 -m venv .venv source .venv/bin/activate pip install -r {baseDir}/requirements-cloud.txt ```
ESPHome: ``` python3 -m venv .venv source .venv/bin/activate pip install -r {baseDir}/requirements-esphome.txt ```
Optional: you can use `uv` instead of `pip` if preferred.
## Output
Scripts emit JSON with: - timestamp - unit - total (best-effort) - top circuits - channels used
## Safety
- Never print secrets (passwords, tokens, keys). - Do not make hardware or panel wiring recommendations.