Emporia Vue

Cloud-REST control and monitoring for Emporia Vue whole-home energy monitors (Vue 2, Vue 3, Vue Utility Connect) and the Vue Smart Plug.

The driver authenticates against the Emporia AWS Cognito user pool with the same email and password the homeowner uses in the Emporia mobile app, then polls per-circuit power against api.emporiaenergy.com. Smart-plug outlets accept on/off; main-panel circuits are read-only sensors.

Prerequisites

• An Emporia account with at least one Vue or Smart Plug already set up via the Emporia mobile app.
• Outbound HTTPS to cognito-idp.us-east-2.amazonaws.com and api.emporiaenergy.com.
• Channel labels assigned in the Emporia app — they make the GEM zone setup much faster.

Setup

1. In GEM, add a new device, pick driver Emporia Vue, and enter:
   • email — the Emporia account email
   • password — the Emporia account password (stored encrypted; never transmitted in clear after auth)
2. Save. The driver will:
   • Run AWS Cognito USER_PASSWORD_AUTH against the public Emporia client id and store the returned IdToken / RefreshToken in memory.
   • GET /customers?email=<email> to resolve the customerGid and write it back to the device as customer_gid.
   • GET /customers/devices to enumerate every Vue, Smart Plug, and EV charger on the account.
3. Run the get_devices command to print the channel list with their deviceGid and channelNum.
4. For every circuit / plug you want to surface, create a GEM zone with:
   • address = <deviceGid>:<channelNum> (e.g. 12345:1)
   • subsystem of your choice (power, sensor, etc.)

Attribute reference

Device

Attribute	Type	Required	Notes
email	string	yes	Emporia account email.
password	string	yes	Emporia account password. Encrypted at rest.
status_interval	int	no	Poll cadence in milliseconds. Defaults to 30000. Minimum 15000.
customer_gid	string	no (driver-set)	Read-only. Populated on first connect.

Zone

Attribute	Type	Notes
address	string	<deviceGid>:<channelNum> — see get_devices output.
label	string	Optional friendly label for the circuit.
state	string	Driver-set: on if instantaneous kW > 0.01, otherwise off.
power	float	Driver-set: instantaneous kilowatts (rounded to 3 decimals).

Zone address format

<deviceGid>:<channelNum>

• deviceGid — integer device id from the Emporia account (run get_devices).
• channelNum — channel number reported by the device. Most main panels run 1 (Mains), 2, 3, … through the configured circuits. Smart plugs typically expose channel 1.

Commands

Command	Args	Description
get_devices	—	Returns the full Emporia device tree, including channels and labels.
get_status	address	Refresh and return the kW reading for a single zone.
on	address	Turn a Smart Plug / EV charger outlet on. No-op (returns an error) for read-only main-panel channels.
off	address	Turn a Smart Plug / EV charger outlet off.
refresh_token	—	Force a Cognito IdToken refresh; useful for diagnostics.

Known limitations

• Authentication uses the public USER_PASSWORD_AUTH flow (matching the mobile app and the PyEmVue community client). SRP is not implemented; if Emporia ever turns off USER_PASSWORD_AUTH on the pool the driver will need an SRP rewrite.
• No native push from the Emporia cloud — every state change is detected via the polling loop. Default cadence is 30 s.
• kW calculation converts the API's per-minute kWh bucket to instantaneous kW (kWh × 60). For a true rolling-average reading, increase status_interval.
• EV-charger granular controls (charge schedule, max amps) are not yet wired through. Only the outlet on/off path is implemented.
• Multi-account environments are not supported on a single device row — create one GEM device per Emporia account.

Troubleshooting

Symptom	Check
cognito auth: NotAuthorizedException	Sign into the Emporia mobile app with the same credentials to confirm they work. Reset the password if necessary.
Driver connects but no zones report	Run get_devices; confirm zone address exactly matches <deviceGid>:<channelNum>.
outlet toggle failed on on / off	The targeted channel is a read-only main-panel circuit. Only Smart Plug and EV-charger outlets accept on/off.
Power values stuck at 0	The Emporia cloud delays new readings by 30–60 s. Wait a full status interval and confirm the channel shows live data in the Emporia app.