powersensor-local 1.0.2__tar.gz

powersensor_local-1.0.2/.gitignore

@@ -0,0 +1,2 @@
+__pycache__
+.*.swp

powersensor_local-1.0.2/LICENSE

@@ -0,0 +1,10 @@
+The MIT License (MIT)
+
+Copyright © 2024 DiUS Computing Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

powersensor_local-1.0.2/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.3
+Name: powersensor-local
+Version: 1.0.2
+Summary: Network-local (non-cloud) interface for Powersensor devices
+Project-URL: Repository, https://github.com/DiUS/python-powersensor_local.git
+Project-URL: Homepage, https://github.com/DiUS/python-powersensor_local
+Project-URL: Issues, https://github.com/DiUS/python-powersensor_local/issues
+Author-email: Jade Mattsson <jmattsson@dius.com.au>
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Powersensor (local)
+
+A small package to interface with the network-local event streams available on
+Powersensor devices. Specifically, this package abstracts away the connections
+to all Powersensor gateway devices (plugs) on the network, and provides a
+uniform event stream from all devices (including sensors relaying their data
+via the gateways).
+
+The main API is in `powersensor_local.devices' via the PowersensorDevices
+class, which provides an abstracted view of the discovered Powersensor devices
+on the local network.
+
+There are also two small utilities included, `ps-events` and `ps-rawfirehose`.
+The former is effectively a consumer of the the PowersensorDevices event
+stream which dumps all events to standard out. The latter, `ps-rawfirehose`
+is a debugging aid which dumps the lower-level event streams from each
+Powersensor gateway.

powersensor_local-1.0.2/README.md

@@ -0,0 +1,17 @@
+# Powersensor (local)
+
+A small package to interface with the network-local event streams available on
+Powersensor devices. Specifically, this package abstracts away the connections
+to all Powersensor gateway devices (plugs) on the network, and provides a
+uniform event stream from all devices (including sensors relaying their data
+via the gateways).
+
+The main API is in `powersensor_local.devices' via the PowersensorDevices
+class, which provides an abstracted view of the discovered Powersensor devices
+on the local network.
+
+There are also two small utilities included, `ps-events` and `ps-rawfirehose`.
+The former is effectively a consumer of the the PowersensorDevices event
+stream which dumps all events to standard out. The latter, `ps-rawfirehose`
+is a debugging aid which dumps the lower-level event streams from each
+Powersensor gateway.

powersensor_local-1.0.2/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "powersensor-local"
+version = "1.0.2"
+description = "Network-local (non-cloud) interface for Powersensor devices"
+authors = [
+  { name = "Jade Mattsson", email = "jmattsson@dius.com.au" },
+]
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Home Automation",
+]
+
+[project.urls]
+Repository = "https://github.com/DiUS/python-powersensor_local.git"
+Homepage = "https://github.com/DiUS/python-powersensor_local"
+Issues = "https://github.com/DiUS/python-powersensor_local/issues"
+
+[project.scripts]
+ps-events = "powersensor_local.events:app"
+ps-rawfirehose = "powersensor_local.rawfirehose:app"
+
+[build-system]
+requires = [ "hatchling" ]
+build-backend = "hatchling.build"

powersensor_local-1.0.2/src/powersensor_local/__init__.py

@@ -0,0 +1,17 @@
+"""Direct (non-cloud) interface to Powersensor devices
+
+This package contains two abstraction layers:
+
+• PowersensorDevices is the main API layer
+• PowersensorListener provides a lower-level abstraction
+
+These are both available within this namespace, or specifically as
+devices.PowersensorDevices and listener.PowersensorListener
+
+The 'events' and 'rawfirehose' modules are helper utilities provided as
+debug aids, which get installed under the names ps-events and ps-rawfirehose
+respectively.
+"""
+__all__ = [ 'devices', 'listener' ]
+from .devices import PowersensorDevices
+from .listener import PowersensorListener

powersensor_local-1.0.2/src/powersensor_local/devices.py

@@ -0,0 +1,321 @@
+import asyncio
+import json
+
+from datetime import datetime, timezone
+
+from .listener import PowersensorListener
+
+EXPIRY_CHECK_INTERVAL_S = 30
+EXPIRY_TIMEOUT_S = 5 * 60
+
+class PowersensorDevices:
+    """Abstraction interface for the unified event stream from all Powersensor 
+    devices on the local network.
+    """
+
+    def __init__(self, bcast_addr='<broadcast>'):
+        """Creates a fresh instance, without scanning for devices."""
+        self._event_cb = None
+        self._ps = PowersensorListener(bcast_addr)
+        self._devices = dict()
+        self._timer = None
+
+    async def start(self, async_event_cb):
+        """Registers the async event callback function and starts the scan
+        of the local network to discover present devices. The callback is
+        of the form
+
+        async def yourcallback(event: dict)
+
+        Known events:
+
+        scan_complete:
+            Indicates the discovery of Powersensor devices has completed.
+            Emitted in response to start() and rescan() calls.
+            The number of found gateways (plugs) is reported.
+
+            { event: "scan_complete", gateway_count: N }
+
+        device_found:
+            A new device found on the network.
+            The order found devices are announced is not fixed.
+
+            { event: "device_found",
+              device_type: "plug" or "sensor",
+              mac: "...",
+            }
+
+            An optional field named "via" is present for sensor devices, and
+            shows the MAC address of the gateway the sensor is communicating
+            via.
+
+        device_lost:
+            A device appears to no longer be present on the network.
+
+            { event: "device_lost", mac: "..." }
+
+
+
+        The events below all have the following common fields:
+
+            { mac: "...", starttime_utc: X }
+            
+            and where applicable, also:
+
+            { via: "..." }
+
+        For brevity's sake they are not shown in the examples below, other
+        then simply as ...
+
+
+        battery_level:
+            The battery level of a sensor.
+
+            { ...,  event: "battery_level", volts: X.Y }
+
+        voltage:
+            The mains voltage as detected by a plug.
+
+            { ..., event: "voltage", volts: X.Y }
+
+        average_power:
+            Reports the average power observed over the reporting duration.
+            May be negative for e.g. solar sensors and house sensors when
+            exporting solar to the grid.
+
+            The summation_joules field is a summation style register which
+            reports accumulated energy. This field is only useful for
+            calculating the delta of energy between two events. The counter
+            will reset to zero if the device is restarted, and is technically
+            subject to overflow, though that is unlikely to be reached.
+            The summation may be negative if solar export is present. The
+            summation may increment or decrement depending on whether energy
+            is being imported from or exported to the grid.
+
+            { ..., event: "average_power",
+              watts: X.Y,
+              durations_s: N.M,
+              summation_joules: J.K,
+            }
+
+            For reports from plugs, the following fields will also be present:
+
+            {
+              ...,
+              volts: X.Y,
+              current: C.D,
+              active_current: E.F,
+              reactive_current: G.H,
+            }
+
+            The (apparent) current, active_current and reactive_current fields
+            are all reported in a unit of Amperes.
+
+        uncalibrated_power:
+            Powersensors require calibrations of their readings before they
+            are able to be converted into a proper power reading. This event
+            is issued for sensor readings prior to such calibration completing.
+            The reported value has no inherent meaning beyond being an
+            indication of the strength of the signal seen by the sensor. It
+            is most definitely NOT in Watts. For most purposes, this event
+            can (and should be) ignored.
+
+            { ..., event: "uncalibrated_power",
+              value: Y.Z,
+              durations_s: N.M,
+            }
+
+        The start function returns the number of found gateway plugs.
+        Powersensor devices aren't found directly as they are typically not
+        on the network, but are instead detected when they relay data through
+        a plug via long-range radio.
+        """
+        self._event_cb = async_event_cb
+        await self._on_scanned(await self._ps.scan())
+        self._timer = self._Timer(EXPIRY_CHECK_INTERVAL_S, self._on_timer)
+        return len(self._ips)
+
+    async def rescan(self):
+        """Performs a fresh scan of the network to discover added devices,
+        or devices which have changed their IP address for some reason."""
+        await self._on_scanned(await self._ps.scan())
+
+    async def stop(self):
+        """Stops the event streaming and disconnects from the devices.
+        To restart the event streaming, call start() again."""
+        await self._ps.unsubscribe()
+        await self._ps.stop()
+        self._event_cb = None
+        if self._timer:
+            self._timer.terminate()
+            self._timer = None
+
+    def subscribe(self, mac):
+        """Subscribes to events from the device with the given MAC address."""
+        device = self._devices.get(mac)
+        if device:
+            device.subscribed = True
+
+    def unsubscribe(self, mac):
+        """Unsubscribes from events from the given MAC address."""
+        device = self._devices.get(mac)
+        if device:
+            device.subscribed = False
+
+    async def _on_scanned(self, ips):
+        self._ips = ips
+        if self._event_cb:
+            ev = {
+                'event': 'scan_complete',
+                'gateway_count': len(ips),
+            }
+            await self._event_cb(ev)
+
+        await self._ps.subscribe(self._on_msg)
+
+    async def _on_msg(self, obj):
+        mac = obj.get('mac')
+        if mac and not self._devices.get(mac):
+            typ = obj.get('device')
+            via = obj.get('via')
+            await self._add_device(mac, typ, via)
+
+        device = self._devices[mac]
+        device.mark_active()
+
+        if self._event_cb and device.subscribed:
+            evs = self._mk_events(obj)
+            if len(evs) > 0:
+                for ev in evs:
+                    await self._event_cb(ev)
+
+    async def _on_timer(self):
+        devices = list(self._devices.values())
+        for device in devices:
+            if device.has_expired():
+                await self._remove_device(device.mac)
+
+    async def _add_device(self, mac, typ, via):
+        self._devices[mac] = self._Device(mac, typ, via)
+        if self._event_cb:
+            ev = {
+                'event': 'device_found',
+                'device_type': typ,
+                'mac': mac,
+            }
+            if via:
+                ev['via'] = via
+            await self._event_cb(ev)
+
+    async def _remove_device(self, mac):
+        if self._devices.get(mac):
+            self._devices.pop(mac)
+            if self._event_cb:
+                ev = {
+                    'event': 'device_lost',
+                    'mac': mac
+                }
+                await self._event_cb(ev)
+
+   ### Event formatting ###
+
+    def _mk_events(self, obj):
+        evs = []
+        typ = obj.get('type')
+        if typ == 'instant_power':
+            unit = obj.get('unit')
+            if unit == 'w' or unit == 'W':
+                evs.append(self._mk_average_power_event(obj))
+            elif unit == 'l' or unit == 'L':
+                evs.append(self.mk_average_water_event(obj))
+                pass # TODO, cl/min?
+            elif unit == 'U':
+                evs.append(self._mk_uncalib_power_event(obj))
+            elif unit == 'I':
+                pass # invalid data / sample failed
+
+            if obj.get('voltage') is not None:
+                evs.append(self._mk_voltage_event(obj))
+
+            if obj.get('batteryMicrovolt') is not None:
+                evs.append(self._mk_battery_event(obj))
+        else:
+            print(obj)
+
+        for ev in evs:
+            ev['mac'] = obj.get('mac')
+            if obj.get('starttime'):
+                ev['starttime_utc'] = obj.get('starttime')
+            if obj.get('via'):
+                ev['via'] = obj.get('via')
+
+        return evs
+
+    def _mk_average_power_event(self, obj):
+        ev = {
+            'event': 'average_power',
+            'watts': obj.get('power'),
+            'duration_s': obj.get('duration'),
+            'summation_joules': obj.get('summation'),
+        }
+        if obj.get('device') == 'plug':
+            ev['volts'] = obj.get('voltage')
+            ev['current'] = obj.get('current')
+            ev['active_current'] = obj.get('active_current')
+            ev['reactive_current'] = obj.get('reactive_current')
+        return ev
+
+    def _mk_uncalib_power_event(self, obj):
+        ev = {
+            'event': 'uncalibrated_power',
+            'value': obj.get('power'),
+            'duration_s': obj.get('duration'),
+        }
+        return ev
+
+    def _mk_voltage_event(self, obj):
+        return {
+            'event': 'voltage',
+            'volts': obj.get('voltage'),
+        }
+
+    def _mk_battery_event(self, obj):
+        return {
+            'event': 'battery_level',
+            'volts': float(obj.get('batteryMicrovolt'))/1000000.0,
+        }
+
+
+    ### Supporting classes ###
+
+    class _Device:
+        def __init__(self, mac, typ, via):
+            self.mac = mac
+            self.type = typ
+            self.via = via
+            self.subscribed = False
+            self._last_active = datetime.now(timezone.utc)
+
+        def mark_active(self):
+            self._last_active = datetime.now(timezone.utc)
+
+        def has_expired(self):
+            now = datetime.now(timezone.utc)
+            delta = now - self._last_active
+            return delta.total_seconds() > EXPIRY_TIMEOUT_S
+
+    class _Timer:
+        def __init__(self, interval_s, callback):
+            self._terminate = False
+            self._interval = interval_s
+            self._callback = callback
+            self._task = asyncio.create_task(self._run())
+
+        def terminate(self):
+            self._terminate = True
+            self._task.cancel()
+
+        async def _run(self):
+            while not self._terminate:
+                await asyncio.sleep(self._interval)
+                await self._callback()

powersensor_local-1.0.2/src/powersensor_local/events.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+
+"""Utility script for accessing the full event stream from all network-local
+Powersensor devices. Intended for debugging use only. Please use the proper
+interface in devices.py rather than parsing the output from this script."""
+
+import asyncio
+import os
+import signal
+import sys
+
+if __name__ == "__main__":
+    # Make CLI runnable from source tree
+    package_source_path = os.path.dirname(os.path.dirname(__file__))
+    sys.path.insert(0, package_source_path)
+    __package__ = "powersensor_local"
+
+from .devices import PowersensorDevices
+
+
+exiting = False
+devices = None
+
+async def do_exit():
+    global exiting
+    global devices
+    if devices != None:
+        await devices.stop()
+    exiting = True
+
+async def on_msg(obj):
+    print(obj)
+    global devices
+    if obj['event'] == 'device_found':
+        devices.subscribe(obj['mac'])
+
+async def main():
+    global devices
+    devices = PowersensorDevices()
+
+    # Signal handler for Ctrl+C
+    def handle_sigint(signum, frame):
+        signal.signal(signal.SIGINT, signal.SIG_DFL)
+        asyncio.create_task(do_exit())
+
+    signal.signal(signal.SIGINT, handle_sigint)
+
+    await devices.start(on_msg)
+
+    # Keep the event loop running until Ctrl+C is pressed
+    while not exiting:
+        await asyncio.sleep(1)
+
+def app():
+    loop = asyncio.new_event_loop()
+    loop.run_until_complete(main())
+    loop.stop()
+
+if __name__ == "__main__":
+    app()

powersensor_local-1.0.2/src/powersensor_local/listener.py

@@ -0,0 +1,116 @@
+import asyncio
+import json
+import socket
+import time
+
+PORT = 49476
+DISCOVERY_TIMEOUT_S = 2
+
+class PowersensorListener(asyncio.DatagramProtocol):
+    def __init__(self, bcast_addr='<broadcast>'):
+        """Initialises a listener object.
+        Optionally takes the broadcast address to use.
+        """
+        self._known_addresses = dict()
+        self._connections = {}
+        self._tasks = dict()
+        self._callback = None
+        self._exiting = False
+        self._bcast = bcast_addr
+
+    async def scan(self):
+        """Scans the local network for discoverable devices with a timeout.
+        Returns the list of IP addresses of the discovered gateways (plugs).
+        """
+        self._known_addresses.clear()
+        loop = asyncio.get_running_loop()
+        transport, _ = await loop.create_datagram_endpoint(
+            self.protocol_factory,
+            family=socket.AF_INET,
+            local_addr=('0.0.0.0', 0))
+        sock = transport.get_extra_info('socket')
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+        message = 'discover()\n'.encode('utf-8')
+
+        timeout = DISCOVERY_TIMEOUT_S
+        while timeout > 0:
+            transport.sendto(message, (self._bcast, PORT))
+            await asyncio.sleep(0.5)
+            timeout -= 0.5
+
+        transport.close()
+        return self._known_addresses.keys()
+
+    def protocol_factory(self):
+        return self
+
+    def datagram_received(self, data, addr):
+        try:
+            response = json.loads(data.decode('utf-8'))
+            ip = response['ip']
+            self._known_addresses[ip] = response['mac']
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    async def subscribe(self, callback):
+        """Subscribes to updates from known devices."""
+        self._callback = callback
+
+        for ip, mac in self._known_addresses.items():
+            if not self._tasks.get(ip):
+                self._tasks[ip] = asyncio.create_task(
+                    self._connect_to_device(ip, mac))
+
+    async def _send_subscribe(self, writer):
+        writer.write(b'subscribe(60)\n')
+        await writer.drain()
+
+    async def _processline(self, ip, mac, reader, writer):
+        data = await reader.readline()
+        if data != b'' and data != b'\n':
+            try:
+                message = json.loads(data.decode('utf-8'))
+                typ = message['type']
+                if typ == 'subscription':
+                    if message['subtype'] == 'warning':
+                        await self._send_subscribe(writer)
+                elif typ == 'discovery':
+                    pass
+                else:
+                    if message.get('device') == 'sensor':
+                        message['via'] = mac
+                    await self._callback(message)
+            except (json.decoder.JSONDecodeError) as ex:
+                print(f"JSON error {ex} from {data}")
+
+    async def _connect_to_device(self, ip, mac, backoff=0):
+        """Connects to a single device and handles reconnections."""
+        backoff += 1
+        try:
+            reader, writer = await asyncio.open_connection(ip, PORT)
+            self._connections[ip] = (reader, writer)
+
+            await self._send_subscribe(writer)
+            backoff = 1
+
+            while not self._exiting:
+                await self._processline(ip, mac, reader, writer)
+
+        except (ConnectionResetError, asyncio.TimeoutError):
+            # Handle disconnection and retry with exponential backoff
+            del self._connections[ip]
+            await asyncio.sleep(min(5 * 60, 2**backoff * 1))
+            return await self._connect_to_device(ip, mac, backoff)
+
+    async def unsubscribe(self):
+        """Unsubscribes from all devices."""
+        for (reader, writer) in self._connections.values():
+            writer.close()
+
+        self._connections = {}
+
+    async def stop(self):
+        """Disconnects from all devices."""
+        self._exiting = True
+        for task in self._tasks.values():
+            await task

powersensor_local-1.0.2/src/powersensor_local/rawfirehose.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+
+"""Utility script for accessing the raw plug subscription data from all
+network-local Powersensor devices. Intended for advanced debugging use only.
+For all other uses, please see the API in devices.py"""
+
+import asyncio
+import os
+import signal
+import sys
+
+if __name__ == "__main__":
+    # Make CLI runnable from source tree
+    package_source_path = os.path.dirname(os.path.dirname(__file__))
+    sys.path.insert(0, package_source_path)
+    __package__ = "powersensor_local"
+
+from .listener import PowersensorListener
+
+
+exiting = False
+ps = None
+
+async def do_exit():
+    global exiting
+    global ps
+    if ps != None:
+        await ps.unsubscribe()
+        await ps.stop()
+    exiting = True
+
+async def on_msg(data):
+    print(data)
+
+async def main():
+    global ps
+    ps = PowersensorListener()
+
+    # Signal handler for Ctrl+C
+    def handle_sigint(signum, frame):
+        signal.signal(signal.SIGINT, signal.SIG_DFL)
+        asyncio.create_task(do_exit())
+
+    signal.signal(signal.SIGINT, handle_sigint)
+
+    # Scan for devices and subscribe upon completion
+    await ps.scan()
+    await ps.subscribe(on_msg)
+
+    # Keep the event loop running until Ctrl+C is pressed
+    while not exiting:
+        await asyncio.sleep(1)
+
+def app():
+    loop = asyncio.new_event_loop()
+    loop.run_until_complete(main())
+    loop.stop()
+
+if __name__ == "__main__":
+    app()