mx-remote 6.2.0__tar.gz → 6.3.0__tar.gz

{mx_remote-6.2.0 → mx_remote-6.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mx_remote
-Version: 6.2.0
+Version: 6.3.0
 Summary: Python 3 library for interfacing with MX Remote compatible devices
 Project-URL: Homepage, https://github.com/opdenkamp/mx-remote/
 Project-URL: Documentation, https://opdenkamp.github.io/mx-remote/

{mx_remote-6.2.0 → mx_remote-6.3.0}/mx_remote/const.py

@@ -14,7 +14,7 @@ Default communication modes:
 """
 import os
 
-VERSION = '6.2.0'
+VERSION = '6.3.0'
 __version__ = VERSION
 
 MX_BCAST_UDP_PORT = 8811

{mx_remote-6.2.0 → mx_remote-6.3.0}/mx_remote/proto/Constants.py

@@ -256,6 +256,7 @@ class DeviceFeature(IntFlag):
 	VLAN               = (1 << 28)
 	'''Tags its uplink by the VLAN configuration it reports, and takes one written to it.'''
 	BOOT_BIT           = (1 << 31)
+	'''Flips on every reboot, so a peer that sees it change knows the device restarted.'''
 
 class OneIPVideoProcessorFeature(IntFlag):
 	'''What a OneIP device's video processor supports, as the device reports it in

mx_remote-6.3.0/mx_remote/proto/FrameDiscover.py

@@ -0,0 +1,44 @@
+######################################################
+##            MX Remote Python Interface            ##
+##                                                  ##
+## author: Lars Op den Kamp (lars@opdenkamp-it.nl)  ##
+## copyright (c) 2021-2026 Op den Kamp IT Solutions ##
+######################################################
+'''Protocol frame for network device discovery.'''
+
+import warnings
+from functools import cached_property
+from .FrameBase import FrameBase
+from ..Interface import DeviceRegistry
+from ..Uid import MxrDeviceUid
+
+# Payload: empty to ask every device, or the 16 byte uid of the one device
+# asked. Any other length asks every device, which is also how a receiver that
+# predates the uid form reads the uid form.
+
+class FrameDiscover(FrameBase):
+    '''Discovery frame that asks devices on the network to send their info.'''
+    @staticmethod
+    def construct(mxr:DeviceRegistry, target:MxrDeviceUid|None=None) -> FrameBase|None:
+        '''Build a discover asking every device, or only target.
+
+        Not refused for a target that predates the uid form: it answers as if
+        every device had been asked.'''
+        payload = bytes([]) if (target is None) else target.byte_value
+        return FrameBase.construct_base(mxr=mxr, opcode=1, protocol=1, payload=payload)
+
+    @cached_property
+    def target_uid(self) -> MxrDeviceUid|None:
+        '''The one device asked, or None when every device is.'''
+        if (self.payload is None) or (len(self.payload) != 16):
+            return None
+        return self.payload_uuid(0)
+
+    def __str__(self) -> str:
+        if (self.target_uid is None):
+            return "discover devices"
+        return f"discover {self.mxr.uid_to_user_string(self.target_uid)}"
+
+def constructFrameDiscover(mxr:DeviceRegistry) -> FrameBase|None:
+    warnings.warn("use FrameDiscover.construct() instead", DeprecationWarning)
+    return FrameDiscover.construct(mxr=mxr)

mx_remote-6.3.0/mx_remote/proto/FrameDiscover.pyi

@@ -0,0 +1,12 @@
+from ..Interface import DeviceRegistry as DeviceRegistry
+from ..Uid import MxrDeviceUid as MxrDeviceUid
+from .FrameBase import FrameBase as FrameBase
+from functools import cached_property
+
+class FrameDiscover(FrameBase):
+    @staticmethod
+    def construct(mxr: DeviceRegistry, target: MxrDeviceUid | None = None) -> FrameBase | None: ...
+    @cached_property
+    def target_uid(self) -> MxrDeviceUid | None: ...
+
+def constructFrameDiscover(mxr: DeviceRegistry) -> FrameBase | None: ...

{mx_remote-6.2.0 → mx_remote-6.3.0}/mx_remote/remote/ConnectionAsync.py

@@ -39,8 +39,11 @@ _LOGGER = logging.getLogger(__name__)
 #
 # The answer to a discover goes to the group, is jittered so a mesh does not
 # reply at once, and is expensive - Remote._background_probe() rate-limits it and
-# stops once every device reports complete. After that the device's own periodic
-# broadcast maintains the state, at worst about 75 seconds stale.
+# stops once every device reports complete. After that a device repeats a frame
+# in only a couple of periodic broadcasts after it changes, and resends
+# everything only every few minutes. So a device first heard, or heard again
+# after it went offline, is asked on its own with a discover whose payload is
+# its 16-byte uid - see Remote._request_state().
 #
 # Signal status (0x31) is the one opcode with a targeted request form of its own,
 # an empty payload or a 16-byte uid, which this library does not send.

{mx_remote-6.2.0 → mx_remote-6.3.0}/mx_remote/remote/Remote.py

@@ -23,8 +23,8 @@ from .ConnectionAsync import ConnectionAsync
 from ..const import MXR_HELLO_INTERVAL_MIN, MXR_HELLO_INTERVAL_RAND, __version__
 from .Device import Device
 from ..Interface import ConnectionCallbacks, DeviceRegistry, MxrDeviceUid, BayLinks, BayBase, DeviceBase, MxrCallbacks, AudioEndpoint, mxr_broadcast_address, OneIPDeviceSettings, OneIPPowerSaveSchedule
-from ..proto.Constants import MXR_PROTOCOL_VERSION
-from ..proto.FrameDiscover import constructFrameDiscover
+from ..proto.Constants import MXR_PROTOCOL_VERSION, DeviceFeature
+from ..proto.FrameDiscover import FrameDiscover, constructFrameDiscover
 from ..proto.Factory import process_mxr_frame
 from ..proto.FrameHello import FrameHello, constructFrameHello
 from ..proto.FramePing import FramePing
@@ -49,6 +49,42 @@ _LOGGER = logging.getLogger(__name__)
 # asks one device.
 _ACCEPT_UNANNOUNCED = (0x00, 0x01, 0x4A)
 
+# How long a discover to every device stands in for asking any one of them, in
+# seconds. Each device answers it with everything it holds, after a jitter of up
+# to a few seconds, so asking one again inside this window repeats an answer
+# already on its way.
+_DISCOVER_COVERS = 60
+
+# What this client had heard of a device before a frame from it: whether it had
+# gone offline, and its reboot toggle as last announced.
+_Heard = tuple[bool, bool]
+
+def _heard(device:DeviceBase) -> _Heard:
+    features = device.features
+    return (not device.online,
+            (features is not None) and (DeviceFeature.BOOT_BIT in features))
+
+def _missed_state(before:_Heard|None, device:DeviceBase) -> bool:
+    '''Whether a device just heard may hold state this client never received.
+
+    A device repeats a frame only for a short while after it changes, so
+    whatever it sent before this client first heard it, or while it was out of
+    earshot, may not come again. before is None for a device this frame
+    registered.
+
+    Not asked: a device whose reboot toggle flipped, or that is about to reboot,
+    because a booting device sends everything it holds; and a management client,
+    which holds nothing to send.
+    '''
+    features = device.features
+    if (features is None) or (DeviceFeature.MANAGER in features) \
+            or (DeviceFeature.STATUS_REBOOTING in features):
+        return False
+    if (before is None):
+        return True
+    away, boot_bit = before
+    return away and (boot_bit == (DeviceFeature.BOOT_BIT in features))
+
 class Remote(DeviceRegistry, ConnectionCallbacks):
     ''' Main component that handles the network connections and registration of remote devices '''
 
@@ -85,6 +121,7 @@ class Remote(DeviceRegistry, ConnectionCallbacks):
         self._target_ip = target_ip
         self._port = port
         self._discover_timeout = 0
+        self._state_request:MxrDeviceUid|None = None
         self._addr_filter = addr_filter
         self._svd = SvdMap()
         if open_connection:
@@ -403,6 +440,21 @@ class Remote(DeviceRegistry, ConnectionCallbacks):
         _LOGGER.debug("discovering devices")
         return self.transmit(pkt.frame)
 
+    def _request_state(self, device:MxrDeviceUid) -> None:
+        '''Ask one device for everything it holds, with a discover naming it.
+
+        Skipped while a discover to every device is recent enough to have
+        covered it. A receiver that predates the named form answers it as a
+        discover to every device, so each one asked costs the whole mesh's state
+        on such a network.
+        '''
+        if ((time.time() - self._discover_timeout) < _DISCOVER_COVERS):
+            return
+        pkt = FrameDiscover.construct(mxr=self, target=device)
+        if (pkt is not None):
+            _LOGGER.debug(f"asking {self.uid_to_user_string(device)} for its state")
+            self.transmit(pkt.frame)
+
     def _send_to_all(self, frame:FrameBase|None) -> bool:
         '''Send a frame to every device, True when all of it was written.'''
         if (frame is None):
@@ -520,8 +572,13 @@ class Remote(DeviceRegistry, ConnectionCallbacks):
         self.tx_discover()
 
     def process_frame(self, timestamp:float, data: bytes, addr: tuple[str, int]) -> None:
-        '''Decode and process a received mx_remote frame.'''
+        '''Decode and process a received mx_remote frame.
+
+        A device that may hold state this client missed is left in
+        _state_request rather than asked here, so replaying a capture sends
+        nothing; on_datagram_received does the asking.'''
         proc = False
+        self._state_request = None
         try:
             frame = process_mxr_frame(mxr=self, timestamp=timestamp, data=data, addr=addr)
             if (frame is not None) and (frame.header.protocol > MXR_PROTOCOL_VERSION):
@@ -557,7 +614,12 @@ class Remote(DeviceRegistry, ConnectionCallbacks):
             raise
         try:
             if (frame is not None) and proc:
+                known = self.remotes.get(frame.remote_id)
+                before = None if (known is None) else _heard(known)
                 frame.process()
+                device = self.remotes.get(frame.remote_id)
+                if (device is not None) and _missed_state(before, device):
+                    self._state_request = frame.remote_id
         except Exception:
             _LOGGER.warning(f"failed to process frame: {traceback.format_exc()}")
             raise
@@ -566,6 +628,8 @@ class Remote(DeviceRegistry, ConnectionCallbacks):
         '''Called when a UDP frame was received.'''
         timestamp = time.time()
         self.process_frame(timestamp=timestamp, data=data, addr=addr)
+        if (self._state_request is not None):
+            self._request_state(self._state_request)
 
     @override
     def on_mxr_update(self, data:Any) -> None:

{mx_remote-6.2.0 → mx_remote-6.3.0}/mx_remote/remote/Remote.pyi

@@ -3,10 +3,10 @@ from ..Interface import AudioEndpoint as AudioEndpoint, BayBase as BayBase, BayL
 from ..Uid import MxrDeviceUid as MxrDeviceUid
 from ..compat import override as override
 from ..const import MXR_HELLO_INTERVAL_MIN as MXR_HELLO_INTERVAL_MIN, MXR_HELLO_INTERVAL_RAND as MXR_HELLO_INTERVAL_RAND, MX_BCAST_UDP_PORT as MX_BCAST_UDP_PORT, MX_MCAST_UDP_IP as MX_MCAST_UDP_IP, MX_MCAST_UDP_PORT as MX_MCAST_UDP_PORT, __version__ as __version__
-from ..proto.Constants import MXR_PROTOCOL_VERSION as MXR_PROTOCOL_VERSION, ONEIP_DEVICE_SETTINGS_REPORTED_ONLY as ONEIP_DEVICE_SETTINGS_REPORTED_ONLY, ONEIP_IR_PROFILE_MAX as ONEIP_IR_PROFILE_MAX, ONEIP_IR_PROFILE_NOT_SET as ONEIP_IR_PROFILE_NOT_SET, OneIPDeviceSetting as OneIPDeviceSetting
+from ..proto.Constants import DeviceFeature as DeviceFeature, MXR_PROTOCOL_VERSION as MXR_PROTOCOL_VERSION, ONEIP_DEVICE_SETTINGS_REPORTED_ONLY as ONEIP_DEVICE_SETTINGS_REPORTED_ONLY, ONEIP_IR_PROFILE_MAX as ONEIP_IR_PROFILE_MAX, ONEIP_IR_PROFILE_NOT_SET as ONEIP_IR_PROFILE_NOT_SET, OneIPDeviceSetting as OneIPDeviceSetting
 from ..proto.Factory import process_mxr_frame as process_mxr_frame
 from ..proto.FrameBase import FrameBase as FrameBase
-from ..proto.FrameDiscover import constructFrameDiscover as constructFrameDiscover
+from ..proto.FrameDiscover import FrameDiscover as FrameDiscover, constructFrameDiscover as constructFrameDiscover
 from ..proto.FrameHello import FrameHello as FrameHello, constructFrameHello as constructFrameHello
 from ..proto.FramePing import FramePing as FramePing
 from ..proto.FrameTime import FrameTime as FrameTime

{mx_remote-6.2.0 → mx_remote-6.3.0}/tests/run.py

@@ -52,6 +52,7 @@ SUITES = [
     'v2ipvlan',     # a V2IP device's VLAN configuration, read and written
     'v2iptestcard', # a V2IP sink's test pattern, tone and lip-sync flash
     'audiolock',    # an audio endpoint's status, and locking its source
+    'staterequest', # a device that may have missed state is asked for it
     'deprecated',   # the V2IP names 5.11.0 exported still resolve, with a warning
 ]
 

mx_remote-6.3.0/tests/staterequest.py

@@ -0,0 +1,119 @@
+######################################################
+##            MX Remote Python Interface            ##
+##                                                  ##
+## author: Lars Op den Kamp (lars@opdenkamp-it.nl)  ##
+## copyright (c) 2021-2026 Op den Kamp IT Solutions ##
+######################################################
+'''A device that may hold state this client missed is asked for it.
+
+A device repeats a frame in only a couple of periodic broadcasts after it
+changes, and resends everything only every few minutes. So a device this client
+first hears, or hears again after counting it offline, is sent a discover
+naming it - unless its own boot or a recent discover to every device already
+covers that.
+'''
+
+import os, struct, sys, time, logging
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+logging.disable(logging.CRITICAL)
+import mx_remote
+from mx_remote.proto.Factory import create_mxr_frame
+from datetime import timedelta
+
+F = mx_remote.DeviceFeature
+ADDR = ('192.0.2.9', 8812)
+HELLO, DISCOVER = 0x00, 0x01
+OURS = bytes(range(0x20, 0x30))
+
+def name(s, sz=16):
+    b = s.encode('ascii')[:sz]
+    return b + bytes(sz - len(b))
+
+def uid(n):
+    return bytes([n]) * 16
+
+def hello(mx, peer, features):
+    mx.on_datagram_received(create_mxr_frame(peer, HELLO, struct.pack('<H', 0x2A) + name('ONEIP')
+                                             + name('SR0001') + name('1.0.0')
+                                             + struct.pack('<I', int(features))), ADDR)
+
+def silence(mx, peer):
+    '''Move the last time peer was heard far enough back to count as offline.'''
+    dev = mx.get_by_uid(mx_remote.MxrDeviceUid(peer))
+    dev._last_ping -= timedelta(seconds=600)
+    assert not dev.online
+
+def discovers(sent):
+    '''The discovers sent, as their payloads.'''
+    return [f[24:] for f in sent if int.from_bytes(f[20:22], 'little') == DISCOVER]
+
+def client():
+    mx = mx_remote.Remote(open_connection=False)
+    mx._uid = OURS
+    mx._hello_due = time.time() + 3600          # nothing is due on the clock
+    sent = []
+    mx.transmit = lambda data: (sent.append(data), len(data))[1]
+    return mx, sent
+
+ROUTING = F.VIDEO_ROUTING
+
+# ---- asked: a device first heard, and one back from offline
+mx, sent = client()
+peer = uid(0x21)
+hello(mx, peer, ROUTING)
+assert discovers(sent) == [peer], 'a device this client first heard'
+print('asked       : a device first heard is sent a discover naming it')
+
+sent.clear()
+hello(mx, peer, ROUTING)
+assert discovers(sent) == [], 'a device that never went away'
+print('asked       : not again while it stays online')
+
+silence(mx, peer)
+hello(mx, peer, ROUTING)
+assert discovers(sent) == [peer], 'a device back from offline'
+print('asked       : again once it comes back from offline')
+
+# ---- not asked: a device that sends everything anyway, or holds nothing
+mx, sent = client()
+rebooted = uid(0x23)
+hello(mx, rebooted, ROUTING)
+silence(mx, rebooted)
+sent.clear()
+hello(mx, rebooted, ROUTING | F.BOOT_BIT)
+assert discovers(sent) == [], 'a device whose reboot toggle flipped'
+print('not asked   : a device whose reboot toggle flipped')
+
+rebooting = uid(0x24)
+hello(mx, rebooting, ROUTING | F.STATUS_REBOOTING)
+assert discovers(sent) == [], 'a device about to reboot'
+print('not asked   : a device about to reboot')
+
+manager = uid(0x25)
+hello(mx, manager, F.MANAGER)
+assert discovers(sent) == [], 'a management client'
+print('not asked   : a management client')
+
+# ---- covered: a discover to every device already asked each one
+mx, sent = client()
+mx.tx_discover()
+sent.clear()
+hello(mx, uid(0x27), ROUTING)
+assert discovers(sent) == [], 'asked again inside the window'
+print('covered     : a discover to every device covers one heard within 60s')
+
+mx._discover_timeout = time.time() - 61
+hello(mx, uid(0x28), ROUTING)
+assert discovers(sent) == [uid(0x28)], 'not asked once the window had passed'
+print('covered     : but not one heard after')
+
+# ---- replay: processing a capture asks nothing, there is no one to ask
+mx = mx_remote.Remote(open_connection=False)
+mx._uid = OURS
+mx.process_frame(time.time(), create_mxr_frame(uid(0x29), HELLO, struct.pack('<H', 0x2A) + name('ONEIP')
+                                               + name('SR0001') + name('1.0.0')
+                                               + struct.pack('<I', int(ROUTING))), ADDR)
+assert mx.get_by_uid(mx_remote.MxrDeviceUid(uid(0x29))) is not None
+print('replay      : a capture registers the device without sending')
+
+print('ALL OK')

mx_remote-6.2.0/mx_remote/proto/FrameDiscover.py

@@ -1,25 +0,0 @@
-######################################################
-##            MX Remote Python Interface            ##
-##                                                  ##
-## author: Lars Op den Kamp (lars@opdenkamp-it.nl)  ##
-## copyright (c) 2021-2026 Op den Kamp IT Solutions ##
-######################################################
-'''Protocol frame for network device discovery.'''
-
-import warnings
-from .FrameBase import FrameBase
-from ..Interface import DeviceRegistry
-
-class FrameDiscover(FrameBase):
-    '''Discovery frame that asks all devices on the network to send their info.'''
-    @staticmethod
-    def construct(mxr:DeviceRegistry) -> FrameBase|None:
-        '''Build a discovery broadcast frame for transmission.'''
-        return FrameBase.construct_base(mxr=mxr, opcode=1, protocol=1)
-
-    def __str__(self) -> str:
-        return "discover devices"
-
-def constructFrameDiscover(mxr:DeviceRegistry) -> FrameBase|None:
-    warnings.warn("use FrameDiscover.construct() instead", DeprecationWarning)
-    return FrameDiscover.construct(mxr=mxr)

mx_remote-6.2.0/mx_remote/proto/FrameDiscover.pyi

@@ -1,8 +0,0 @@
-from ..Interface import DeviceRegistry as DeviceRegistry
-from .FrameBase import FrameBase as FrameBase
-
-class FrameDiscover(FrameBase):
-    @staticmethod
-    def construct(mxr: DeviceRegistry) -> FrameBase | None: ...
-
-def constructFrameDiscover(mxr: DeviceRegistry) -> FrameBase | None: ...