Sense Energy Monitor

The sense_energy driver reads whole-home power data from a Sense monitor via the Sense cloud API. It authenticates with the same email and password used by the Sense mobile app, opens the realtime WebSocket feed, and surfaces total instantaneous power, voltage, frequency, and per-device on/off + power for every appliance Sense has discovered on the panel.

There is no published LAN protocol for Sense — all traffic goes through api.sense.com and clientrt.sense.com.

Prerequisites

• A Sense account with at least one monitor visible in the Sense mobile app.
• The Sense account does not have MFA / two-factor enabled. This driver does not currently implement the MFA challenge flow — disable MFA in the Sense app before adding the device.
• Outbound HTTPS to api.sense.com (port 443) and outbound WSS to clientrt.sense.com (port 443).

Setup

1. Confirm the mobile app works. If you cannot sign in to the Sense mobile app, the driver cannot either.
2. Create the device under System → Devices with driver sense_energy. Set:
   • username — Sense account email
   • password — Sense account password (stored encrypted)
3. Confirm connection. From the Script Console:

   await gem.command({device: <device_id>, action: 'get_monitors'});

   You should see one or more entries with id, serial_number, etc. If the account owns multiple monitors, set monitor_id explicitly:

   await gem.setAttribute('device', <device_id>, 'monitor_id', '<monitor_id>');

4. List the discovered devices.

   await gem.command({device: <device_id>, action: 'get_devices'});

   The response contains one entry per appliance Sense has trained, with id, name, icon, and avg_monthly_kwh.
5. (Optional) Create one zone per device under System → Zones with address set to the Sense device id. The realtime feed writes state (on / off) and power (watts) on every update.
6. Watch the whole-home total. The driver writes the following attributes on the controller device itself:
   • power — total instantaneous watts
   • solar_power — solar production watts (if the monitor reports it)
   • voltage — line voltage
   • frequency — line frequency (Hz)

Attributes

Device

Attribute	Required	Type	Notes
username	yes	string	Sense account email.
password	yes	string (secure)	Sense account password.
monitor_id	no	string	Auto-selected if the account owns a single monitor.
status_interval	no	int	How often (ms) to refetch the discovered-device list. Realtime power flows over the WebSocket separately. Default 60000, minimum 30000.

Runtime-written attributes (populated from the realtime feed):

Attribute	Type	Source
power	int	total instantaneous watts (payload.w)
solar_power	int	solar watts (payload.solar_w, when present)
voltage	float	line voltage
frequency	float	line frequency (Hz)

Zone

Zone address must equal a Sense device id. The realtime feed writes:

Attribute	Type	Source
state	string	on while the device appears in payload.devices[], off when it drops out.
power	int	watts reported by Sense for that device in the most recent realtime sample.

Commands

Name	Args	Description
get_monitors	—	List monitors on the account.
get_devices	—	List discovered devices with current power and average monthly kWh.
get_realtime	—	Return the most recent realtime sample seen on the WebSocket (total W, solar W, active device count).
reconnect	—	Force a re-authentication and WebSocket reconnect.

Known limitations

• Read-only. Sense is a monitor, not a controller. There is no path to switch a circuit on or off through this driver.
• MFA accounts cannot authenticate. A future revision will support the MFA challenge flow.
• Realtime is WebSocket-only. If outbound WSS to clientrt.sense.com is blocked, only the discovered-device list is available (via HTTP polling).
• Sense pauses the realtime feed while the Sense mobile app is in the foreground. The driver reconnects automatically when the app moves to the background.
• Device retraining can shuffle device IDs. When Sense splits or merges a learned device, its id may change; existing zone addresses need to be updated manually.

Troubleshooting

Symptom	Check
authenticate http 401 with mfa_required	The account has MFA enabled. Disable MFA in the Sense app to use this driver.
authenticate http 401 without mfa_required	Wrong email/password. Verify in the Sense mobile app.
WebSocket repeatedly closes within seconds	Either the Sense mobile app is in the foreground (vendor pauses the realtime feed) or the access token was rejected. The driver re-authenticates and reconnects automatically; watch the device log for repeated realtime close followed by realtime open cycles.
Zones never flip to on	Confirm the zone address matches a device.id from get_devices. Sense devices that have not been confidently detected yet will not appear in the realtime feed.
power attribute on the device updates but voltage / frequency don't	Older monitors don't always report voltage/Hz in the realtime payload — this is expected.