Add documentation clarifications

Author: jmattsson

src/powersensor_local/devices.py

@@ -51,6 +51,9 @@ class _PowersensorDevicesBase:
 
     **device_found**
         A device has been discovered or re-discovered.
+        Note that due to device hardware limitations, role information is NOT
+        reliably available at this time, and therefore not included in this
+        message.
         ``{ event: "device_found", device_type: "plug"|"sensor", mac: "..." }``
 
     **device_lost**
@@ -71,6 +74,9 @@ class _PowersensorDevicesBase:
     ``device_found`` for the same sensor MAC.
 
     Note: ``scan_complete`` is only emitted by PowersensorLegacyDevices.
+
+    The typical event cadence is 30 seconds, but may be as frequent as every
+    second, or less frequent in case of packet loss.
     """
 
     def __init__(
@@ -121,7 +127,13 @@ def _maybe_log(self, level: _LogLevel, msg: str, *args) -> None:
     # ------------------------------------------------------------------
 
     def subscribe(self, mac: str) -> None:
-        """Subscribe to events from the device with the given MAC address."""
+        """Subscribe to events from the device with the given MAC address.
+
+        Subscriptions are automatically removed if a device disappears,
+        ensuring no accumulating resource leakage. Use the `device_found`
+        message to resubscribe if a subscription is still desired when the
+        device returns, if it returns.
+        """
         device = self._devices.get(mac)
         if device:
             device.subscribed = True

src/powersensor_local/virtual_household.py

@@ -150,6 +150,17 @@ def __init__(self, with_solar: bool):
           processing, but until such a time may generate incorrect values
           for home usage. Similarly, if this is set to True but no solar
           exists, no events may be generated.
+
+          It is expected that a user of this library will persist this flag
+          and restore it upon reinitialisation. Powersensor kits may or may
+          not include a solar sensor, but once an installation has been
+          observed to have a solar sensor this is expected to stay so.
+          In particular, this is to guard against the (somewhat common)
+          scenario where a solar sensor runs out of battery and stops sending
+          data. Without having persisted the with_solar flag, the system
+          would be generating incorrect data until such a time the solar
+          sensor is recharged. It is vastly preferable to have the system
+          show no data than show incorrect data.
         """
         super().__init__()
         self._expect_solar = with_solar

src/powersensor_local/xlatemsg.py

@@ -136,6 +136,9 @@ def translate_raw_message(message: dict, relay_mac: str):
         through. When the message origin is not the plug, the events returned
         from this function will have "via": relay_mac added to denote what
         plug is acting as the relay for them.
+        Note that the relaying plug for a sensor can change at any point
+        without warning, and the topology is not stable. The relay_mac is
+        intended as a diagnostic aid only.
 
     Returns:
 
@@ -243,7 +246,15 @@ def translate_raw_message(message: dict, relay_mac: str):
           - "starttime_utc": Seconds since the Unix Epoch, in UTC.
           - "volts": The current battery level, in Volts. Sensors operate
             on 3.7V nominally, with a fully charged battery at around 4.2V.
-            Precise battery curves vary individually.
+            Precise battery curves vary individually. It is intentional that
+            we do not attempt to map these to a percentage value here, as
+            between individual differences and environmental conditions they
+            are bound to be inaccurate. Short of characterising each battery
+            in its environment, any such mapping will be inaccurate. It can
+            be argued that users wishing a simple percentage display are best
+            off using a simple linear extrapolation across the middle part of
+            the curve, e.g. 3.3V and 4.15V. It's not entirely accurate, but
+            it's also not useless.
 
       - "radio_signal_quality": An event reporting radio signal quality for
         a sensor. Note that this is for the long-range radio comms with the