mx-remote 9.3.0__tar.gz → 9.4.0__tar.gz

{mx_remote-9.3.0 → mx_remote-9.4.0}/PKG-INFO

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

@@ -432,6 +432,14 @@ application, which this client announces itself as, and only from protocol
 after its last page, so one is refused before it is sent. Nothing acknowledges
 the pages; `oneip_sink_sdp` reads what the output reports next.
 
+From protocol 0x31 an output also reports the description it plays, when it
+starts a stream other than by its mesh controller's command and when asked:
+
+```python
+await sink.request_oneip_sink_description()   # False below protocol 0x31
+print(sink.oneip_sink_description)   # None until reported, and once it plays none
+```
+
 ### Overlay sync
 
 A management unit can have the other units copy its overlay captions, logo
@@ -553,8 +561,14 @@ await device.set_unit_network(UnitNetConfig(
     ip='10.1.2.3', netmask='255.255.255.0', gateway='10.1.2.254', dns1='10.1.2.254'))
 await device.confirm_unit_network()    # keep it, once the unit reports it
 await device.set_unit_dhcp()
+await device.locate_unit(timed=True)   # flash its LED for 30 s; timed=False until stopped
+await device.stop_locating_unit()
 ```
 
+A unit is located only once its status carries `UnitFlag.LOCATE_SUPPORTED`. Its
+board-ID LED flashes and an output shows "Locate Device"; `UnitFlag.LOCATE` in
+the cached status says so from the moment the command is sent.
+
 A changed IP configuration applies at once and reverts unless the mesh
 controller confirms it in time; `status.network_pending` says whether it still
 waits. Each command returns False without sending for a device that is not a

{mx_remote-9.3.0 → mx_remote-9.4.0}/mx_remote/Interface.py

@@ -3355,6 +3355,15 @@ class DeviceBase(ABC):
     async def confirm_unit_network(self) -> bool:
         '''keep the unit's pending IP configuration'''
 
+    @abstractmethod
+    async def locate_unit(self, timed:bool=False) -> bool:
+        '''flash the unit's board-ID LED and show "Locate Device" on its output,
+        for 30 s when timed is set, until stop_locating_unit() otherwise'''
+
+    @abstractmethod
+    async def stop_locating_unit(self) -> bool:
+        '''stop locating the unit'''
+
     @property
     @abstractmethod
     def oneip_downmix(self) -> OneIPDownmix|None:
@@ -3740,6 +3749,18 @@ class DeviceBase(ABC):
     async def request_oneip_sink_sdp(self) -> bool:
         '''ask this OneIP output what it plays from a session description now'''
 
+    @property
+    @abstractmethod
+    def oneip_sink_description(self) -> str|None:
+        '''The session description this OneIP output last reported playing, None
+        until it has and once it reports playing none. An output reports one
+        when it starts a stream other than by its mesh controller's command,
+        and when asked with request_oneip_sink_description().'''
+
+    @abstractmethod
+    async def request_oneip_sink_description(self) -> bool:
+        '''ask this OneIP output for the session description it plays'''
+
     @abstractmethod
     async def set_oneip_test_pattern(self, pattern:OneIPTestPattern, colour:int=0) -> bool:
         '''show a test pattern on this sink's output'''

{mx_remote-9.3.0 → mx_remote-9.4.0}/mx_remote/Interface.pyi

@@ -1210,6 +1210,10 @@ class DeviceBase(ABC):
     async def set_unit_network(self, network: UnitNetConfig) -> bool: ...
     @abstractmethod
     async def confirm_unit_network(self) -> bool: ...
+    @abstractmethod
+    async def locate_unit(self, timed: bool = False) -> bool: ...
+    @abstractmethod
+    async def stop_locating_unit(self) -> bool: ...
     @property
     @abstractmethod
     def oneip_downmix(self) -> OneIPDownmix | None: ...
@@ -1393,6 +1397,11 @@ class DeviceBase(ABC):
     async def set_oneip_sdp_screen(self, screen: int) -> bool: ...
     @abstractmethod
     async def request_oneip_sink_sdp(self) -> bool: ...
+    @property
+    @abstractmethod
+    def oneip_sink_description(self) -> str | None: ...
+    @abstractmethod
+    async def request_oneip_sink_description(self) -> bool: ...
     @abstractmethod
     async def set_oneip_test_pattern(self, pattern: OneIPTestPattern, colour: int = 0) -> bool: ...
     @abstractmethod

{mx_remote-9.3.0 → mx_remote-9.4.0}/mx_remote/const.py

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

{mx_remote-9.3.0 → mx_remote-9.4.0}/mx_remote/proto/Constants.py

@@ -684,6 +684,11 @@ class UnitFlag(IntFlag):
 	'''The boot count is reported.'''
 	FAN_SPEED                  = (1 << 15)
 	'''The fan speed is reported.'''
+	LOCATE_SUPPORTED           = (1 << 16)
+	'''The unit takes UnitCommandKind.LOCATE.'''
+	LOCATE                     = (1 << 17)
+	'''The unit is being located: its board-ID LED flashes, and an output shows
+	"Locate Device".'''
 
 class UnitCommandKind(IntEnum):
 	'''What a unit command asks of its unit.'''
@@ -695,6 +700,8 @@ class UnitCommandKind(IntEnum):
 	'''Change the IP configuration.'''
 	NET_CONFIRM             = 3
 	'''Keep a pending IP configuration.'''
+	LOCATE                  = 4
+	'''Start or stop locating the unit.'''
 
 class UnitCommandFlag(IntFlag):
 	'''The flags of a unit command.'''
@@ -703,6 +710,11 @@ class UnitCommandFlag(IntFlag):
 	already.'''
 	DHCP  = (1 << 1)
 	'''With NET_CONFIG: use DHCP, ignoring the addresses.'''
+	LOCATE_ON    = (1 << 2)
+	'''With LOCATE: locate it until stopped. Neither this nor LOCATE_TIMED
+	stops it.'''
+	LOCATE_TIMED = (1 << 3)
+	'''With LOCATE: locate it for 30 s.'''
 
 UNIT_MAX_TEMPERATURES = 6
 """The most temperature sensors a unit reports."""

{mx_remote-9.3.0 → mx_remote-9.4.0}/mx_remote/proto/Constants.pyi

@@ -271,16 +271,21 @@ class UnitFlag(IntFlag):
     POWER_CHECK: Incomplete
     BOOT_COUNT: Incomplete
     FAN_SPEED: Incomplete
+    LOCATE_SUPPORTED: Incomplete
+    LOCATE: Incomplete
 
 class UnitCommandKind(IntEnum):
     CLEAR_STATUS: int
     VIDEO_PROCESSOR_UPGRADE: int
     NET_CONFIG: int
     NET_CONFIRM: int
+    LOCATE: int
 
 class UnitCommandFlag(IntFlag):
     FORCE: Incomplete
     DHCP: Incomplete
+    LOCATE_ON: Incomplete
+    LOCATE_TIMED: Incomplete
 
 UNIT_MAX_TEMPERATURES: int
 

{mx_remote-9.3.0 → mx_remote-9.4.0}/mx_remote/proto/FrameV2IPSinkSdp.py

@@ -7,6 +7,7 @@
 '''Protocol frame for V2IP_SINK_SDP (opcode 0x52): what a OneIP output plays
 from a session description, and the commands that hand it one.'''
 
+from dataclasses import dataclass
 from functools import cached_property
 import ipaddress
 import struct
@@ -30,9 +31,11 @@ from ..Uid import MxrDeviceUid
 #
 # A page follows the header with the description's length, the page's offset
 # into it and the page's length, all u16, two reserved bytes, and at most
-# SDP_PAGE_LEN bytes of the description.
+# SDP_PAGE_LEN bytes of the description. An output reports the description it
+# plays in pages of the same shape.
 SDP_HEADER_SIZE = 20
 _STATUS_SIZE = 80
+_PAGE_HEADER_SIZE = 8
 
 SDP_STATUS = 0
 '''The output's report.'''
@@ -44,10 +47,35 @@ SDP_SCREEN = 3
 '''What the output shows while it plays audio alone, in the value byte.'''
 SDP_REQUEST = 4
 '''Report now.'''
+SDP_DESCRIPTION = 5
+'''A page of the description an output reports playing.'''
+
+SDP_REQUEST_DESCRIPTION = (1 << 0)
+'''The bit of a request's value that asks for the description too.'''
+
+SDP_DESCRIPTION_PROTOCOL = 0x31
+'''The first protocol version whose outputs report the description they play.
+Not the stamp: that is the opcode's, and an output between the two answers a
+request for the description with its status alone.'''
+
+SDP_PAGE_TIMEOUT = 5
+'''How long an output may take between two pages of one description, in
+seconds, before the pages it sent are dropped.'''
 
 SDP_PAGE_LEN = 1024
 '''The most bytes of a session description one page carries.'''
 
+@dataclass(frozen=True)
+class SdpDescriptionPage:
+    '''A page of the description an output reports playing.'''
+    total: int
+    '''The length of the whole description.'''
+    offset: int
+    '''Where this page's text starts in it.'''
+    text: bytes
+    timestamp: float
+    '''When the page arrived.'''
+
 def _cstr(data:bytes) -> str:
     return data.split(b'\0', 1)[0].decode('ascii', errors='replace')
 
@@ -109,14 +137,38 @@ class FrameV2IPSinkSdp(FrameBase):
             # that fills its field stops one byte short of it.
             name=_cstr(s[24:71]), layout=_cstr(s[72:79]))
 
+    @cached_property
+    def description_page(self) -> SdpDescriptionPage|None:
+        '''A page of the description the output reports playing, None for
+        another type, for a page whose header names a device other than its
+        sender, which only the output itself reports, and for a frame too short
+        for the text its page header declares.'''
+        p = self.payload or b''
+        if (self.kind != SDP_DESCRIPTION) or (self.target_uid != self.remote_id) \
+                or (len(p) < SDP_HEADER_SIZE + _PAGE_HEADER_SIZE):
+            return None
+        total, offset, length = struct.unpack_from('<HHH', p, SDP_HEADER_SIZE)
+        start = SDP_HEADER_SIZE + _PAGE_HEADER_SIZE
+        if (len(p) < start + length):
+            return None
+        return SdpDescriptionPage(total=total, offset=offset, text=bytes(p[start:start + length]),
+                                  timestamp=self.timestamp)
+
     @override
     def process(self) -> None:
-        '''Record an output's report against the output that sent it. The other
-        types are commands for an output, which only that output acts on.'''
-        if ((status := self.status) is not None) and ((dev := self.remote_device) is not None):
+        '''Record an output's report and the pages of its description against
+        the output that sent them. The other types are commands for an output,
+        which only that output acts on.'''
+        if ((dev := self.remote_device) is None):
+            return
+        if ((status := self.status) is not None):
             dev.on_mxr_update(status)
+        elif ((page := self.description_page) is not None):
+            dev.on_mxr_update(page)
 
     def __str__(self) -> str:
         if (self.status is not None):
             return f"OneIP sink SDP: {self.status}"
+        if ((page := self.description_page) is not None):
+            return f"OneIP sink SDP description: bytes {page.offset} to {page.offset + len(page.text)} of {page.total}"
         return f"OneIP sink SDP command {self.kind} for {self.uid_to_user_string(self.target_uid)}"

{mx_remote-9.3.0 → mx_remote-9.4.0}/mx_remote/proto/FrameV2IPSinkSdp.pyi

@@ -3,6 +3,8 @@ from ..Uid import MxrDeviceUid as MxrDeviceUid
 from ..compat import override as override
 from .Constants import OneIPSdpClockMode as OneIPSdpClockMode, OneIPSdpClockState as OneIPSdpClockState, OneIPSdpEncoding as OneIPSdpEncoding, OneIPSdpFlag as OneIPSdpFlag, OneIPSdpMediaClock as OneIPSdpMediaClock, OneIPSdpRefClock as OneIPSdpRefClock
 from .FrameBase import FrameBase as FrameBase
+from _typeshed import Incomplete
+from dataclasses import dataclass
 from functools import cached_property
 from typing import Any
 
@@ -12,8 +14,19 @@ SDP_PAGE: int
 SDP_STOP: int
 SDP_SCREEN: int
 SDP_REQUEST: int
+SDP_DESCRIPTION: int
+SDP_REQUEST_DESCRIPTION: Incomplete
+SDP_DESCRIPTION_PROTOCOL: int
+SDP_PAGE_TIMEOUT: int
 SDP_PAGE_LEN: int
 
+@dataclass(frozen=True)
+class SdpDescriptionPage:
+    total: int
+    offset: int
+    text: bytes
+    timestamp: float
+
 class FrameV2IPSinkSdp(FrameBase):
     @staticmethod
     def construct_command(mxr: DeviceRegistry, target: Any, target_uid: MxrDeviceUid, kind: int, value: int = 0) -> FrameBase | None: ...
@@ -25,5 +38,7 @@ class FrameV2IPSinkSdp(FrameBase):
     def kind(self) -> int | None: ...
     @cached_property
     def status(self) -> OneIPSinkSdp | None: ...
+    @cached_property
+    def description_page(self) -> SdpDescriptionPage | None: ...
     @override
     def process(self) -> None: ...

{mx_remote-9.3.0 → mx_remote-9.4.0}/mx_remote/remote/Device.py

@@ -74,6 +74,7 @@ from ..const import MXR_CONFIG_TIMEOUT
 from ..Uid import MxrDeviceUid
 from typing import Any, Callable
 from ..compat import override
+from dataclasses import replace
 from datetime import datetime
 from enum import Enum
 import logging
@@ -88,13 +89,14 @@ from ..proto.Constants import (MXR_PROTOCOL_VERSION_SLOW_HELLO, ONEIP_DOWNMIX_LF
                               ONEIP_IR_PROFILE_MAX, ONEIP_IR_PROFILE_NOT_SET, ONEIP_VLAN_PORT_SFP,
                               ONEIP_DEVICE_SETTINGS_BLOCK, ONEIP_DSCP_MAX,
                               ONEIP_PTP_DOMAIN_MAX, ONEIP_SDP_MAX, OneIPPowerSaveLevel, OneIPPtpFlag, OneIPPtpMode, UnitCommandFlag,
-                              UnitCommandKind)
+                              UnitCommandKind, UnitFlag)
 from ..proto.FrameUnitCommand import FrameUnitCommand
 from ..proto.FrameV2IPAudio import AUDIO_LAYOUT_SINCE, FrameV2IPAudio
 from ..proto.FrameV2IPDeviceConfiguration import FrameV2IPDeviceConfiguration
 from ..proto.FrameV2IPOsdSync import FrameV2IPOsdSync, OSD_KIND_MESSAGE_REQUEST, OSD_KIND_MESSAGE_SET
 from ..proto.FrameV2IPPrivacy import FrameV2IPPrivacy
-from ..proto.FrameV2IPSinkSdp import FrameV2IPSinkSdp, SDP_REQUEST, SDP_SCREEN, SDP_STOP
+from ..proto.FrameV2IPSinkSdp import (FrameV2IPSinkSdp, SdpDescriptionPage, SDP_DESCRIPTION_PROTOCOL, SDP_PAGE_TIMEOUT,
+                                      SDP_REQUEST, SDP_REQUEST_DESCRIPTION, SDP_SCREEN, SDP_STOP)
 from ..proto.FrameV2IPTestcard import (FrameV2IPTestcard, TESTCARD_REQUEST, TESTCARD_SET,
                                        TESTCARD_PART_PATTERN, TESTCARD_PART_TONE, TESTCARD_PART_SYNC)
 
@@ -177,6 +179,11 @@ class Device(DeviceBase):
 		self._unit_status:UnitStatus|None = None
 		self._v2ip_testcard:OneIPTestcard|None = None
 		self._v2ip_sink_sdp:OneIPSinkSdp|None = None
+		self._v2ip_sink_description:str|None = None
+		# The pages of a description the output is still sending: its whole
+		# length, the bytes received so far from offset 0, and when the last
+		# page arrived.
+		self._v2ip_sink_description_pages:tuple[int, bytes, float]|None = None
 		self._v2ip_privacy:OneIPPrivacy|None = None
 		self._osd_sync:OsdSync|None = None
 		self._osd_sync_report:OsdSyncReport|None = None
@@ -1076,9 +1083,18 @@ class Device(DeviceBase):
 				self.callbacks.on_osd_message_changed(self, data)
 				self.call_callbacks()
 		elif isinstance(data, OneIPSinkSdp):
-			if (self._v2ip_sink_sdp != data):
-				self._v2ip_sink_sdp = data
+			changed = (self._v2ip_sink_sdp != data)
+			self._v2ip_sink_sdp = data
+			if not data.active:
+				# A description is reported when a stream starts, so one that
+				# has stopped leaves none behind it.
+				self._v2ip_sink_description_pages = None
+				changed |= (self._v2ip_sink_description is not None)
+				self._v2ip_sink_description = None
+			if changed:
 				self.call_callbacks()
+		elif isinstance(data, SdpDescriptionPage):
+			self._on_sink_description_page(data)
 		elif isinstance(data, OneIPPrivacy):
 			if (self._v2ip_privacy != data):
 				self._v2ip_privacy = data
@@ -1275,6 +1291,39 @@ class Device(DeviceBase):
 		upgrade_unit_video_processor() apply.'''
 		return self._unit_command(UnitCommandKind.NET_CONFIRM)
 
+	async def locate_unit(self, timed:bool=False) -> bool:
+		'''Locate this unit: its board-ID LED flashes, and an output shows
+		"Locate Device" on its display. For 30 s when timed is set, until
+		stop_locating_unit() otherwise.
+
+		Refused until the unit has reported its status, and for one whose report
+		lacks UnitFlag.LOCATE_SUPPORTED. The cached status takes UnitFlag.LOCATE
+		at once, as the mesh controller's copy does; the unit reports its own
+		within 2 s, and again when a timed locate ends. Otherwise as
+		upgrade_unit_video_processor().
+		'''
+		return self._locate(UnitCommandFlag.LOCATE_TIMED if timed else UnitCommandFlag.LOCATE_ON)
+
+	async def stop_locating_unit(self) -> bool:
+		'''Stop locating this unit. As locate_unit().'''
+		return self._locate(UnitCommandFlag(0))
+
+	def _locate(self, flags:UnitCommandFlag) -> bool:
+		'''The one send behind the locate methods.'''
+		if ((status := self._unit_status) is None):
+			_LOGGER.warning(f"not locating {self}: it has not reported its status")
+			return False
+		if (UnitFlag.LOCATE_SUPPORTED not in status.flags):
+			_LOGGER.warning(f"not locating {self}: it cannot be located")
+			return False
+		if not self._unit_command(UnitCommandKind.LOCATE, flags):
+			return False
+		located = int(status.flags) & ~int(UnitFlag.LOCATE)
+		if flags:
+			located |= int(UnitFlag.LOCATE)
+		self.on_mxr_update(replace(status, flags=UnitFlag(located)))
+		return True
+
 	def _unit_command(self, command:UnitCommandKind, flags:UnitCommandFlag=UnitCommandFlag(0),
 	                  network:UnitNetConfig|None=None) -> bool:
 		'''The one send behind the unit command methods.'''
@@ -1888,6 +1937,55 @@ class Device(DeviceBase):
 		play_oneip_sdp().'''
 		return self._send_sink_sdp_command(SDP_REQUEST, 0)
 
+	@property
+	@override
+	def oneip_sink_description(self) -> str|None:
+		return self._v2ip_sink_description
+
+	async def request_oneip_sink_description(self) -> bool:
+		'''Ask this OneIP output what it plays from a session description and for
+		the description itself, which oneip_sink_description then reads. An
+		output that plays none sends its status alone.
+
+		Refused below protocol 0x31, where an output ignores the ask for the
+		description. Otherwise as play_oneip_sdp().'''
+		if (self.protocol != 0) and (self.protocol < SDP_DESCRIPTION_PROTOCOL):
+			_LOGGER.warning(f"not asking {self} for its session description: protocol {self.protocol:#04x} "
+			                f"predates it")
+			return False
+		return self._send_sink_sdp_command(SDP_REQUEST, SDP_REQUEST_DESCRIPTION)
+
+	def _on_sink_description_page(self, page:SdpDescriptionPage) -> None:
+		'''Put together the description this output reports playing, one page
+		at a time, as a unit puts together the pages it is sent.
+
+		A page at offset 0 starts a description of 1 to ONEIP_SDP_MAX bytes.
+		Every later page has to continue it: at the offset received so far, for
+		the same length, within SDP_PAGE_TIMEOUT of the page before. Anything
+		else drops the pages received, and the description is kept once its
+		last byte is in.'''
+		pending = self._v2ip_sink_description_pages
+		self._v2ip_sink_description_pages = None
+		if (page.offset == 0):
+			if not (1 <= page.total <= ONEIP_SDP_MAX):
+				return
+			data = b''
+		elif (pending is not None) and (pending[0] == page.total) and (len(pending[1]) == page.offset) \
+				and (page.timestamp - pending[2] <= SDP_PAGE_TIMEOUT):
+			data = pending[1]
+		else:
+			return
+		if (len(data) + len(page.text) > page.total):
+			return
+		data += page.text
+		if (len(data) < page.total):
+			self._v2ip_sink_description_pages = (page.total, data, page.timestamp)
+			return
+		description = data.decode('utf-8', errors='replace')
+		if (self._v2ip_sink_description != description):
+			self._v2ip_sink_description = description
+			self.call_callbacks()
+
 	@property
 	@override
 	def oneip_privacy(self) -> OneIPPrivacy|None:

{mx_remote-9.3.0 → mx_remote-9.4.0}/mx_remote/remote/Device.pyi

@@ -3,7 +3,7 @@ from ..Uid import MxrDeviceUid as MxrDeviceUid
 from ..compat import override as override
 from ..const import MXR_CONFIG_TIMEOUT as MXR_CONFIG_TIMEOUT
 from ..proto.BayConfig import BayConfig as BayConfig
-from ..proto.Constants import BayFeaturesMask as BayFeaturesMask, DeviceFeature as DeviceFeature, MXR_PROTOCOL_VERSION_SLOW_HELLO as MXR_PROTOCOL_VERSION_SLOW_HELLO, MXR_SCALING_FLAG_AUTO_SCALING as MXR_SCALING_FLAG_AUTO_SCALING, MXR_SCALING_FLAG_MODE_VALID as MXR_SCALING_FLAG_MODE_VALID, MXR_SCALING_FLAG_OPTIONS_VALID as MXR_SCALING_FLAG_OPTIONS_VALID, MxrSignalType as MxrSignalType, ONEIP_DEVICE_SETTINGS_BLOCK as ONEIP_DEVICE_SETTINGS_BLOCK, ONEIP_DEVICE_SETTING_SWITCHES as ONEIP_DEVICE_SETTING_SWITCHES, ONEIP_DOWNMIX_LFE_MAX as ONEIP_DOWNMIX_LFE_MAX, ONEIP_DSCP_MAX as ONEIP_DSCP_MAX, ONEIP_IR_PROFILE_MAX as ONEIP_IR_PROFILE_MAX, ONEIP_IR_PROFILE_NOT_SET as ONEIP_IR_PROFILE_NOT_SET, ONEIP_PTP_DOMAIN_MAX as ONEIP_PTP_DOMAIN_MAX, ONEIP_SDP_MAX as ONEIP_SDP_MAX, ONEIP_VLAN_PORT_SFP as ONEIP_VLAN_PORT_SFP, OSD_MESSAGE_TEXT_MAX as OSD_MESSAGE_TEXT_MAX, OneIPDeviceSetting as OneIPDeviceSetting, OneIPPowerSaveLevel as OneIPPowerSaveLevel, OneIPPtpFlag as OneIPPtpFlag, OneIPPtpMode as OneIPPtpMode, OneIPTestPattern as OneIPTestPattern, OneIPToneMode as OneIPToneMode, OneIPVideoProcessorFeature as OneIPVideoProcessorFeature, OneIPVlanFlag as OneIPVlanFlag, OsdMessageFlag as OsdMessageFlag, OsdMessagePriority as OsdMessagePriority, UnitCommandFlag as UnitCommandFlag, UnitCommandKind as UnitCommandKind
+from ..proto.Constants import BayFeaturesMask as BayFeaturesMask, DeviceFeature as DeviceFeature, MXR_PROTOCOL_VERSION_SLOW_HELLO as MXR_PROTOCOL_VERSION_SLOW_HELLO, MXR_SCALING_FLAG_AUTO_SCALING as MXR_SCALING_FLAG_AUTO_SCALING, MXR_SCALING_FLAG_MODE_VALID as MXR_SCALING_FLAG_MODE_VALID, MXR_SCALING_FLAG_OPTIONS_VALID as MXR_SCALING_FLAG_OPTIONS_VALID, MxrSignalType as MxrSignalType, ONEIP_DEVICE_SETTINGS_BLOCK as ONEIP_DEVICE_SETTINGS_BLOCK, ONEIP_DEVICE_SETTING_SWITCHES as ONEIP_DEVICE_SETTING_SWITCHES, ONEIP_DOWNMIX_LFE_MAX as ONEIP_DOWNMIX_LFE_MAX, ONEIP_DSCP_MAX as ONEIP_DSCP_MAX, ONEIP_IR_PROFILE_MAX as ONEIP_IR_PROFILE_MAX, ONEIP_IR_PROFILE_NOT_SET as ONEIP_IR_PROFILE_NOT_SET, ONEIP_PTP_DOMAIN_MAX as ONEIP_PTP_DOMAIN_MAX, ONEIP_SDP_MAX as ONEIP_SDP_MAX, ONEIP_VLAN_PORT_SFP as ONEIP_VLAN_PORT_SFP, OSD_MESSAGE_TEXT_MAX as OSD_MESSAGE_TEXT_MAX, OneIPDeviceSetting as OneIPDeviceSetting, OneIPPowerSaveLevel as OneIPPowerSaveLevel, OneIPPtpFlag as OneIPPtpFlag, OneIPPtpMode as OneIPPtpMode, OneIPTestPattern as OneIPTestPattern, OneIPToneMode as OneIPToneMode, OneIPVideoProcessorFeature as OneIPVideoProcessorFeature, OneIPVlanFlag as OneIPVlanFlag, OsdMessageFlag as OsdMessageFlag, OsdMessagePriority as OsdMessagePriority, UnitCommandFlag as UnitCommandFlag, UnitCommandKind as UnitCommandKind, UnitFlag as UnitFlag
 from ..proto.FrameBase import FrameBase as FrameBase
 from ..proto.FrameFirmwareVersion import FirmwareType as FirmwareType, FirmwareVersion as FirmwareVersion
 from ..proto.FrameHello import FrameHello as FrameHello
@@ -20,7 +20,7 @@ from ..proto.FrameV2IPDeviceConfiguration import FrameV2IPDeviceConfiguration as
 from ..proto.FrameV2IPMultiviewer import FrameV2IPMultiviewer as FrameV2IPMultiviewer, V2IPMultiviewerConfig as V2IPMultiviewerConfig
 from ..proto.FrameV2IPOsdSync import FrameV2IPOsdSync as FrameV2IPOsdSync, OSD_KIND_MESSAGE_REQUEST as OSD_KIND_MESSAGE_REQUEST, OSD_KIND_MESSAGE_SET as OSD_KIND_MESSAGE_SET
 from ..proto.FrameV2IPPrivacy import FrameV2IPPrivacy as FrameV2IPPrivacy
-from ..proto.FrameV2IPSinkSdp import FrameV2IPSinkSdp as FrameV2IPSinkSdp, SDP_REQUEST as SDP_REQUEST, SDP_SCREEN as SDP_SCREEN, SDP_STOP as SDP_STOP
+from ..proto.FrameV2IPSinkSdp import FrameV2IPSinkSdp as FrameV2IPSinkSdp, SDP_DESCRIPTION_PROTOCOL as SDP_DESCRIPTION_PROTOCOL, SDP_PAGE_TIMEOUT as SDP_PAGE_TIMEOUT, SDP_REQUEST as SDP_REQUEST, SDP_REQUEST_DESCRIPTION as SDP_REQUEST_DESCRIPTION, SDP_SCREEN as SDP_SCREEN, SDP_STOP as SDP_STOP, SdpDescriptionPage as SdpDescriptionPage
 from ..proto.FrameV2IPStats import FrameV2IPStats as FrameV2IPStats
 from ..proto.FrameV2IPTestcard import FrameV2IPTestcard as FrameV2IPTestcard, TESTCARD_PART_PATTERN as TESTCARD_PART_PATTERN, TESTCARD_PART_SYNC as TESTCARD_PART_SYNC, TESTCARD_PART_TONE as TESTCARD_PART_TONE, TESTCARD_REQUEST as TESTCARD_REQUEST, TESTCARD_SET as TESTCARD_SET
 from ..proto.Multiviewer import MultiviewerAspectRatio as MultiviewerAspectRatio, MultiviewerBoolSetting as MultiviewerBoolSetting, MultiviewerConfig as MultiviewerConfig, MultiviewerEDIDTemplate as MultiviewerEDIDTemplate, MultiviewerHDCPMode as MultiviewerHDCPMode, MultiviewerITCMode as MultiviewerITCMode, MultiviewerOutputMode as MultiviewerOutputMode, MultiviewerPipPosition as MultiviewerPipPosition, MultiviewerPipSize as MultiviewerPipSize, MultiviewerSource as MultiviewerSource, MultiviewerViewMode as MultiviewerViewMode
@@ -254,6 +254,8 @@ class Device(DeviceBase):
     async def set_unit_dhcp(self) -> bool: ...
     async def set_unit_network(self, network: UnitNetConfig) -> bool: ...
     async def confirm_unit_network(self) -> bool: ...
+    async def locate_unit(self, timed: bool = False) -> bool: ...
+    async def stop_locating_unit(self) -> bool: ...
     async def ping(self) -> bool: ...
     async def mesh_promote(self) -> bool: ...
     async def auto_assign_oneip_source_addresses(self) -> bool: ...
@@ -301,6 +303,10 @@ class Device(DeviceBase):
     async def request_oneip_sink_sdp(self) -> bool: ...
     @property
     @override
+    def oneip_sink_description(self) -> str | None: ...
+    async def request_oneip_sink_description(self) -> bool: ...
+    @property
+    @override
     def oneip_privacy(self) -> OneIPPrivacy | None: ...
     async def request_oneip_privacy(self) -> bool: ...
     def __eq__(self, other: Any) -> bool: ...

{mx_remote-9.3.0 → mx_remote-9.4.0}/tests/unit.py

@@ -180,6 +180,36 @@ for bad in (UnitNetConfig('0.0.0.0', '255.255.255.0'), UnitNetConfig('239.1.2.3'
     refused(unit.set_unit_network(bad), f'network [{bad}]')
 print('refusals    : old units, non-units and networks a unit cannot hold')
 
+# A unit says it can be located in bit 16 of its status flags, and that it is
+# being located in bit 17.
+def report_flags(flags):
+    return struct.pack('<I', flags) + report()[4:]
+found = hello(uid(0x23), 0x2C, UNIT)
+rx(uid(0x23), 0x4F, report_flags(1 << 16))
+assert found.unit_status.flags == UnitFlag.LOCATE_SUPPORTED, found.unit_status.flags
+rx(uid(0x23), 0x4F, report_flags(1 << 17))
+assert found.unit_status.flags == UnitFlag.LOCATE, found.unit_status.flags
+
+# A unit is located for 30 s or until stopped, only once it has reported that it
+# can be, and the cached status says so at once.
+located = hello(uid(0x24), 0x2C, UNIT)
+refused(located.locate_unit(timed=True), 'a unit that has not reported its status')
+rx(uid(0x24), 0x4F, report_flags(int(UnitFlag.FAN_SPEED)))
+refused(located.locate_unit(timed=True), 'a unit that cannot be located')
+refused(located.stop_locating_unit(), 'a unit that cannot be located')
+rx(uid(0x24), 0x4F, report_flags(int(UnitFlag.LOCATE_SUPPORTED | UnitFlag.FAN_SPEED) | (1 << 30)))
+assert call(located.locate_unit(timed=True)) is True
+p = command()
+assert p[:16] == uid(0x24) and p[16:18] == bytes([4, 0x08]), p.hex()
+assert UnitFlag.LOCATE in located.unit_status.flags, 'the cached status was not marked located'
+assert call(located.locate_unit()) is True
+assert command()[16:18] == bytes([4, 0x04]), 'until stopped'
+assert call(located.stop_locating_unit()) is True
+assert command()[16:18] == bytes([4, 0x00]), 'stop'
+assert located.unit_status.flags == UnitFlag(int(UnitFlag.LOCATE_SUPPORTED | UnitFlag.FAN_SPEED) | (1 << 30)), \
+    f'a stop clears the flag and nothing else: {located.unit_status.flags!r}'
+print('locate      : timed, until stopped and stop, once the unit says it can be')
+
 # -------------------------------------------------- a command seen on the wire
 
 # Decoded for the log; a command too short to hold its fields carries none.

{mx_remote-9.3.0 → mx_remote-9.4.0}/tests/v2ipsdp.py

@@ -37,10 +37,10 @@ def name(s, sz=16):
     b = s.encode('ascii')[:sz]
     return b + bytes(sz - len(b))
 
-def rx(sender, opcode, payload=b'', protocol=0x2E):
+def rx(sender, opcode, payload=b'', protocol=0x2E, when=0.0):
     frame = bytearray(create_mxr_frame(sender, opcode, payload))
     frame[2] = protocol
-    mx.process_frame(0.0, bytes(frame), ADDR)
+    mx.process_frame(when, bytes(frame), ADDR)
 
 def hello(sender, protocol, features):
     rx(sender, 0x00, struct.pack('<H', protocol) + name('ONEIP') + name('P8SN%08d' % sender[0])
@@ -114,4 +114,82 @@ refused(old.request_oneip_sink_sdp(), 'an output below 0x2E')
 refused(out.set_oneip_sdp_screen(256), 'a screen past the field')
 print('refusals    : nothing an output ignores is sent')
 
+# ------------------------------------------------------------------- description
+def page(header_uid, total, offset, text):
+    '''One page of the description an output reports playing, its reserved
+    bytes set.'''
+    return (header_uid + bytes([5, 0xA5, 0x5A, 0xC3]) + struct.pack('<HHH', total, offset, len(text))
+            + bytes([0x96, 0x69]) + text)
+
+# Put together from its pages and kept once its last byte is in, and a status
+# playing nothing clears it.
+desc = hello(uid(0x20), 0x31, DeviceFeature.ONEIP_SINK)
+sdp = bytes(ord('a') + i % 26 for i in range(1500))
+rx(uid(0x20), 0x52, page(uid(0x20), 1500, 0, sdp[:1024]))
+assert desc.oneip_sink_description is None, 'kept early'
+rx(uid(0x20), 0x52, page(uid(0x20), 1500, 1024, sdp[1024:]))
+assert desc.oneip_sink_description == sdp.decode(), desc.oneip_sink_description
+playing = bytearray(report(uid(0x20)))
+rx(uid(0x20), 0x52, bytes(playing))
+assert desc.oneip_sink_description == sdp.decode(), 'a status playing something cleared it'
+playing[20] &= ~int(OneIPSdpFlag.ACTIVE)
+rx(uid(0x20), 0x52, bytes(playing))
+assert desc.oneip_sink_description is None, 'a status playing nothing left it'
+# A status playing nothing also drops the pages of one still arriving.
+rx(uid(0x20), 0x52, page(uid(0x20), 4, 0, b'ab'))
+rx(uid(0x20), 0x52, bytes(playing))
+rx(uid(0x20), 0x52, page(uid(0x20), 4, 2, b'cd'))
+assert desc.oneip_sink_description is None, 'pages from before a stop were kept'
+print('description : put together from its pages, and cleared by a status playing nothing')
+
+# A page that does not continue the description drops the pages received, and a
+# description is started only at offset 0, by the output itself, for 1 to
+# ONEIP_SDP_MAX bytes. Each case would complete a description if the rule it
+# breaks were not checked, so none passes on the back of another's drop.
+desc = hello(uid(0x21), 0x31, DeviceFeature.ONEIP_SINK)
+me = uid(0x21)
+short = page(me, 1, 0, b'ab')[:-1]
+for frames in ((page(me, 6, 0, b'ab'), page(me, 6, 4, b'cdef'), page(me, 6, 2, b'cdef')),  # out of order
+               (page(me, 6, 0, b'ab'), page(me, 4, 2, b'cd')),                            # another length
+               (page(me, 4, 0, b'ab'), page(me, 4, 2, b'cde')),                           # past the end
+               (page(me, 1, 1, b'b'),),                                                   # not at 0
+               (short,),                                                                  # text cut short
+               (page(me, ONEIP_SDP_MAX + 1, 0, b'ab'),),                                  # too long
+               (page(me, 0, 0, b''),),                                                    # empty
+               (page(uid(0x77), 2, 0, b'ab'),),                                           # someone else's
+               (page(me, 2, 0, b'ab')[:25],),                                             # page header cut short
+               (me + bytes([1]) + page(me, 2, 0, b'ab')[17:],)):                          # a page handed to it
+    for f in frames:
+        rx(me, 0x52, f)
+    assert desc.oneip_sink_description is None, frames
+# Restarting at 0 starts afresh.
+for f in (page(me, 4, 0, b'xx'), page(me, 4, 0, b'ab'), page(me, 4, 2, b'cd')):
+    rx(me, 0x52, f)
+assert desc.oneip_sink_description == 'abcd', desc.oneip_sink_description
+longest = hello(uid(0x22), 0x31, DeviceFeature.ONEIP_SINK)
+rx(uid(0x22), 0x52, page(uid(0x22), ONEIP_SDP_MAX, 0, b'z' * 1024))
+rx(uid(0x22), 0x52, page(uid(0x22), ONEIP_SDP_MAX, 1024, b'z' * 1024))
+assert longest.oneip_sink_description == 'z' * ONEIP_SDP_MAX
+print('pages       : only pages that continue a description from offset 0 are kept')
+
+# Pages more than 5 s apart are dropped.
+slow = hello(uid(0x23), 0x31, DeviceFeature.ONEIP_SINK)
+rx(uid(0x23), 0x52, page(uid(0x23), 4, 0, b'ab'), when=100.0)
+rx(uid(0x23), 0x52, page(uid(0x23), 4, 2, b'cd'), when=105.001)
+assert slow.oneip_sink_description is None, 'a page after 5 s was kept'
+rx(uid(0x23), 0x52, page(uid(0x23), 4, 0, b'ab'), when=100.0)
+rx(uid(0x23), 0x52, page(uid(0x23), 4, 2, b'cd'), when=105.0)
+assert slow.oneip_sink_description == 'abcd', slow.oneip_sink_description
+print('timeout     : pages at most 5 s apart')
+
+# Asking for it sets bit 0 of the request's value, at the opcode's stamp, and is
+# refused below 0x31, where an output ignores the bit.
+sent.clear()
+assert call(desc.request_oneip_sink_description()) is True
+assert int.from_bytes(sent[-1][20:22], 'little') == 0x52 and sent[-1][2] == 0x2E, sent[-1][:24].hex()
+assert sent[-1][24:] == uid(0x21) + bytes([4, 1, 0, 0]), sent[-1][24:].hex()
+refused(hello(uid(0x24), 0x30, DeviceFeature.ONEIP_SINK).request_oneip_sink_description(), 'an output below 0x31')
+refused(src.request_oneip_sink_description(), 'a device that is not a OneIP output')
+print('request     : bit 0 of the value, refused below 0x31')
+
 print('ALL OK')