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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mx_remote
-Version: 6.0.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.0.0 → mx_remote-6.3.0}/docs/oneip.md

@@ -308,6 +308,7 @@ itself, a profile out of range, or a schedule time that is not a time of day.
 # mesh operations
 await device.mesh_promote()   # promote to mesh master
 await device.mesh_remove()    # remove from mesh
+await source.auto_assign_oneip_source_addresses()  # drop addresses set by hand
 
 # firmware versions
 if device.oneip_firmware_versions:
@@ -315,6 +316,12 @@ if device.oneip_firmware_versions:
         print(f"{fw_type}: {fw.version}")
 ```
 
+A OneIP source acts on `auto_assign_oneip_source_addresses()` only from
+management, which this client announces itself as, and nothing acknowledges it:
+the source's next configuration report carries the addresses it ends up with, in
+`oneip_details`. A device that is not a source, or announces less than protocol
+0x2B, would ignore the operation, so it is refused before anything is sent.
+
 ### Time zone and time
 
 The mesh controller announces its time zone and clock with every periodic

{mx_remote-6.0.0 → mx_remote-6.3.0}/mx_remote/Interface.py

@@ -2804,6 +2804,10 @@ class DeviceBase(ABC):
     async def mesh_promote(self) -> bool:
         '''promote to mesh master'''
 
+    @abstractmethod
+    async def auto_assign_oneip_source_addresses(self) -> bool:
+        '''hand this OneIP source's stream addresses back to automatic assignment'''
+
     @abstractmethod
     async def mesh_remove(self) -> bool:
         '''remove from mesh'''

{mx_remote-6.0.0 → mx_remote-6.3.0}/mx_remote/Interface.pyi

@@ -1059,6 +1059,8 @@ class DeviceBase(ABC):
     @abstractmethod
     async def mesh_promote(self) -> bool: ...
     @abstractmethod
+    async def auto_assign_oneip_source_addresses(self) -> bool: ...
+    @abstractmethod
     async def mesh_remove(self) -> bool: ...
     @abstractmethod
     async def read_stats(self, enable: bool) -> bool: ...

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

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

{mx_remote-6.0.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.0.0 → mx_remote-6.3.0}/mx_remote/proto/FrameMeshOperation.py

@@ -22,6 +22,8 @@ class MeshOperation(IntEnum):
     REGENERATE_ADDRESSES = 3
     REPORT_CONTROLLER = 4
     PROMOTE_CONTROLLER = 5
+    AUTO_ADDRESSES = 6
+    '''Hand the target's source addresses back to automatic assignment.'''
     REPORT_MEMBERSHIP = 0xFF
 
     def __str__(self) -> str:
@@ -37,6 +39,8 @@ class MeshOperation(IntEnum):
             return "report controller"
         if self.value == MeshOperation.PROMOTE_CONTROLLER.value:
             return "promote controller"
+        if self.value == MeshOperation.AUTO_ADDRESSES.value:
+            return "automatic addresses"
         if self.value == MeshOperation.REPORT_MEMBERSHIP.value:
             return "report membership"
         return "unknown"
@@ -66,6 +70,13 @@ _WIRE_SIZE = 40
 _ACCEPT_PROTOCOL = 0x1A
 _INSTALLER_PROTOCOL = 0x1D
 
+AUTO_ADDRESSES_PROTOCOL = 0x2B
+'''The first protocol version whose devices can act on AUTO_ADDRESSES.
+
+Not the stamp: that is this opcode's, and a device between the two takes the
+frame and ignores an operation it does not know. Not every device on this
+version has it either, but none below it does.'''
+
 class FrameMeshOperation(FrameBase):
     ''' Mesh operation '''
 

{mx_remote-6.0.0 → mx_remote-6.3.0}/mx_remote/proto/FrameMeshOperation.pyi

@@ -11,8 +11,11 @@ class MeshOperation(IntEnum):
     REGENERATE_ADDRESSES: int
     REPORT_CONTROLLER: int
     PROMOTE_CONTROLLER: int
+    AUTO_ADDRESSES: int
     REPORT_MEMBERSHIP: int
 
+AUTO_ADDRESSES_PROTOCOL: int
+
 class FrameMeshOperation(FrameBase):
     @staticmethod
     def construct(mxr: DeviceRegistry, operation: MeshOperation, target: DeviceBase, option: DeviceBase | None = None) -> FrameBase | None: ...

{mx_remote-6.0.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.0.0 → mx_remote-6.3.0}/mx_remote/remote/Device.py

@@ -35,7 +35,7 @@ from ..Interface import (
 )
 from ..proto.BayConfig import BayConfig
 from ..proto.FrameHello import FrameHello
-from ..proto.FrameMeshOperation import MeshOperation, FrameMeshOperation
+from ..proto.FrameMeshOperation import AUTO_ADDRESSES_PROTOCOL, MeshOperation, FrameMeshOperation
 from ..proto.FrameV2IPStats import FrameV2IPStats
 from ..proto.FrameNetworkStatus import NetworkPortStatus
 from ..proto.FrameReboot import FrameReboot
@@ -1057,6 +1057,30 @@ class Device(DeviceBase):
 			return True
 		return False
 
+	async def auto_assign_oneip_source_addresses(self) -> bool:
+		'''Hand this OneIP source's stream addresses back to automatic assignment,
+		undoing addresses that were set on it by hand.
+
+		The device takes this only from management, which this client announces
+		itself as. Nothing acknowledges it: the device's next configuration
+		report carries the addresses it ends up with, and oneip_details reads
+		them.
+
+		Refused for a device that is not a OneIP source, and for one below
+		protocol 0x2B, which predates the operation and ignores it.
+		'''
+		if (self.features is None) or (DeviceFeature.ONEIP_SOURCE not in self.features):
+			_LOGGER.warning(f"not handing the addresses of {self} back to automatic assignment: it is not a OneIP source")
+			return False
+		if (self.protocol != 0) and (self.protocol < AUTO_ADDRESSES_PROTOCOL):
+			_LOGGER.warning(f"not handing the addresses of {self} back to automatic assignment: it advertises "
+			                f"protocol {self.protocol:02X} and the operation needs {AUTO_ADDRESSES_PROTOCOL:02X}")
+			return False
+		frame = FrameMeshOperation.construct(mxr=self.registry, target=self, operation=MeshOperation.AUTO_ADDRESSES)
+		if (frame is None):
+			return False
+		return self.registry.transmit(frame.frame) == len(frame.frame)
+
 	async def mesh_remove(self) -> bool:
 		'''Remove this device from the mesh network.'''
 		frame = FrameMeshOperation.construct(mxr=self.registry, target=self, operation=MeshOperation.UNREGISTER)

{mx_remote-6.0.0 → mx_remote-6.3.0}/mx_remote/remote/Device.pyi

@@ -7,7 +7,7 @@ from ..proto.Constants import DeviceFeature as DeviceFeature, MXR_PROTOCOL_VERSI
 from ..proto.FrameBase import FrameBase as FrameBase
 from ..proto.FrameFirmwareVersion import FirmwareType as FirmwareType, FirmwareVersion as FirmwareVersion
 from ..proto.FrameHello import FrameHello as FrameHello
-from ..proto.FrameMeshOperation import FrameMeshOperation as FrameMeshOperation, MeshOperation as MeshOperation
+from ..proto.FrameMeshOperation import AUTO_ADDRESSES_PROTOCOL as AUTO_ADDRESSES_PROTOCOL, FrameMeshOperation as FrameMeshOperation, MeshOperation as MeshOperation
 from ..proto.FrameNetworkStatus import NetworkPortStatus as NetworkPortStatus
 from ..proto.FramePing import FramePing as FramePing
 from ..proto.FrameReboot import FrameReboot as FrameReboot
@@ -223,6 +223,7 @@ class Device(DeviceBase):
     async def reboot(self) -> bool: ...
     async def ping(self) -> bool: ...
     async def mesh_promote(self) -> bool: ...
+    async def auto_assign_oneip_source_addresses(self) -> bool: ...
     async def mesh_remove(self) -> bool: ...
     async def read_stats(self, enable: bool) -> bool: ...
     async def set_oneip_auto_scaling(self, enabled: bool) -> bool: ...

{mx_remote-6.0.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.0.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.0.0 → mx_remote-6.3.0}/tests/mesh.py

@@ -20,6 +20,7 @@ import mx_remote
 from mx_remote import MxrDeviceUid, OneIPDeviceSetting as S, OneIPDeviceSettings, OneIPPowerSaveSchedule
 from mx_remote.proto.Constants import (ONEIP_IR_PROFILE_MAX, ONEIP_IR_PROFILE_NOT_SET,
                                        ONEIP_MINUTES_PER_DAY)
+from mx_remote.proto.Constants import MXR_OPCODE_VERSIONS
 from mx_remote.proto.Factory import create_mxr_frame
 
 ADDR = ('192.0.2.9', 8812)
@@ -165,4 +166,41 @@ for ok in (OneIPDeviceSettings(valid=S.IR_PROFILE, ir_profile=ONEIP_IR_PROFILE_M
     assert call(mx.set_all_oneip_device_settings(ok)) is True, f'{ok} was refused'
 print('all refused : what every device would ignore is not sent')
 
+# -------------------------------------------- a source's automatic addresses
+
+# Mesh operation 6 names the source, with the parameter and padding zero, and
+# is stamped as every mesh operation is.
+def device(uid, protocol, features, serial):
+    rx_from(uid, 0x00, struct.pack('<H', protocol) + name('OneIP') + name(serial) + name('5.0.0')
+                       + struct.pack('<I', int(features)), protocol=protocol)
+    return mx.get_by_uid(MxrDeviceUid(uid))
+
+def rx_from(uid, opcode, payload, protocol):
+    frame = bytearray(create_mxr_frame(uid, opcode, payload))
+    frame[2] = protocol
+    mx.process_frame(time.time(), bytes(frame), ADDR)
+
+SOURCE = mx_remote.DeviceFeature.ONEIP_SOURCE
+src = device(bytes([0x50]) * 16, 0x2B, SOURCE, 'AA0001')
+old = device(bytes([0x51]) * 16, 0x2A, SOURCE, 'AA0002')
+sink_only = device(bytes([0x52]) * 16, 0x2B, mx_remote.DeviceFeature.ONEIP_SINK, 'AA0003')
+
+sent.clear()
+assert call(src.auto_assign_oneip_source_addresses()) is True
+frame = sent.pop()
+assert opcode(frame) == 0x3B and frame[2] == MXR_OPCODE_VERSIONS[0x3B], (opcode(frame), frame[2])
+p = frame[24:]
+assert len(p) == 40, 'a receiver drops a mesh operation shorter than 40 bytes'
+assert p[:4] == bytes([6, 0, 0, 0]), p[:4].hex()
+assert p[4:20] == bytes([0x50]) * 16, 'the frame names another device'
+assert p[20:] == bytes(20), 'the parameter and padding'
+
+refused(old.auto_assign_oneip_source_addresses(), 'a source below 0x2B, which ignores the operation')
+refused(sink_only.auto_assign_oneip_source_addresses(), 'a device that is not a source')
+
+mx.transmit = lambda data: 0
+assert call(src.auto_assign_oneip_source_addresses()) is False, 'a failed send reported success'
+mx.transmit = lambda data: (sent.append(data), len(data))[1]
+print('auto addrs  : mesh operation 6 to a source on 0x2B; anything else is refused')
+
 print('ALL OK')

{mx_remote-6.0.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.0.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.0.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: ...