API Reference
Direct (non-cloud) interface to Powersensor devices
This package contains various abstractions for interacting with Powersensor devices on the local network.
The recommended approach is to use mDNS to discover plugs via their service “_powersensor._udp.local” (or “_powersensor._tcp.local” for TCP transport), and then instantiate a PlugApi to obtain the event stream from each plug. Note that the plugs are only capable of handling a single TCP connection at a time, so UDP is the preferred transport. Up to 5 concurrent subscriptions are supported over UDP. The interfaces provided by PlugListenerUdp and PlugListenerTCP are identical; switching between them should be trivial.
A legacy abstraction is also provided via PowersensorDevices, which uses an older way of discovering plugs, and then funnels all the event streams through a single callback.
Lower-level interfaces are available in the PlugListenerUdp and PlugListenerTcp classes, though they are not recommended for general use.
Additionally, a convenience abstraction for translating some of the events into a household view is available in VirtualHousehold.
Quick overview: • PlugApi is the recommended API layer • PlugListenerUdp is the UDP lower-level abstraction used by PlugApi • PlugListenerTcp is the TCP lower-level abstraction used by PlugApi • PowersensorDevices is the legacy main API layer • LegacyDiscovery provides access to the legacy discovery mechanism • VirtualHousehold can be used to translate events into a household view
The ‘plugevents’ and ‘rawplug’ modules are helper utilities provided as debug aids, which get installed under the names ps-plugevents and ps-rawplug respectively. There is also the legacy ‘events’ debug aid which get installed nder the names ps-events, and offers up the events from PowersensorDevices.
- class powersensor_local.PlugApi(mac, ip, port=49476, proto='udp')[source]
Bases:
AsyncEventEmitterThe primary interface to access the interpreted event stream from a plug.
The plug may be relaying messages from one or more sensors, in addition to its own reports.
Acts as an AsyncEventEmitter. Events which can be registered for are documented in xlatemsg.translate_raw_message.
- connect()[source]
Initiates a connection to the plug.
Will automatically retry on failure or if the connection is lost, until such a time disconnect() is called.
- property ip_address
- class powersensor_local.PlugListenerTcp(ip, port=49476)[source]
Bases:
AsyncEventEmitterAn interface class for accessing the event stream from a single plug. The following events may be emitted:
(“connecting”) Whenever a connection attempt is made.
(“connected”) When a connection is successful.
(“disconnected”) When a connection is dropped, be it intentional or not.
(“message”,{…}) For each event message received from the plug. The
plug’s JSON message is decoded into a dict which is passed as the second argument to the registered event handler(s). - (“malformed”,line) If JSON decoding of a message fails. The raw line is included (as a byte string).
The event handlers must be async.
- connect()[source]
Initiates the connection to the plug. The object will automatically retry as necessary if/when it can’t connect to the plug, until such a time disconnect() is called.
- async disconnect()[source]
Goes through the disconnection process towards a plug. No further automatic reconnects will take place, until connect() is called.
- property ip
- class powersensor_local.PlugListenerUdp(ip, port=49476)[source]
Bases:
AsyncEventEmitter,DatagramProtocolAn interface class for accessing the event stream from a single plug. The following events may be emitted:
(“connecting”) Whenever a connection attempt is made.
(“connected”) When a connection is successful.
(“disconnected”) When a connection is dropped, be it intentional or not.
(“message”,{…}) For each event message received from the plug. The
plug’s JSON message is decoded into a dict which is passed as the second argument to the registered event handler(s). - (“malformed”,line) If JSON decoding of a message fails. The raw line is included (as a byte string).
The event handlers must be async.
- connect()[source]
Initiates the connection to the plug. The object will automatically retry as necessary if/when it can’t connect to the plug, until such a time disconnect() is called.
- connection_lost(exc)[source]
Called when the connection is lost or closed.
The argument is an exception object or None (the latter meaning a regular EOF is received or the connection was aborted or closed).
- connection_made(transport)[source]
Called when a connection is made.
The argument is the transport representing the pipe connection. To receive data, wait for data_received() calls. When the connection is closed, connection_lost() is called.
- async disconnect()[source]
Goes through the disconnection process towards a plug. No further automatic reconnects will take place, until connect() is called.
- class powersensor_local.VirtualHousehold(with_solar)[source]
Bases:
AsyncEventEmitterClass for processing average_power and summation_energy events into to/from grid, solar generation, and home usage events.
To use, simply feed the appropriate PlugApi events to the process_average_power_event and process_summation_event member functions.
Point-in-time power flow events include:
home_usage
from_grid
to_grid (only for solar kits)
solar_generation (only for solar kits)
These all have an event payload in the form:
{ timestamp_utc: , watts: }
Energy summation events include:
home_usage_summation
from_grid_summation
to_grid_summation (only for solar kits)
solar_generation_summation (only for solar kits)
These all have an event payload in the form:
{ timestamp_utc: , summation_resettime_utc: , summation_joules: }
Summations may reset at any time. Track the summation_resettime_utc field to take note of summation resets.
- class Counters(resettime_utc, solar_generation, to_grid, from_grid, home_use)[source]
Bases:
object