mx-remote 5.6.0__tar.gz → 5.8.0__tar.gz

{mx_remote-5.6.0 → mx_remote-5.8.0}/AGENTS.md

@@ -85,6 +85,21 @@ Version is single-sourced in `mx_remote/const.py` (`VERSION = '...'`); `pyprojec
 reads it via regex, so bump it there only. Release commits follow the convention
 `bump to X.Y.Z`.
 
+### Releases
+`.github/workflows/release.yml` builds and uploads, so a release needs no local
+build and no PyPI credentials:
+
+```sh
+# after the `bump to X.Y.Z` commit is pushed
+git tag -a vX.Y.Z -m 'mx-remote X.Y.Z' && git push origin vX.Y.Z
+gh release create vX.Y.Z --title 'mx-remote X.Y.Z' --verify-tag --notes '...'
+```
+
+Publishing the release runs the suites against the tag, builds the wheel and
+sdist, uploads them to PyPI over Trusted Publishing, and attaches them to the
+release page. Notes stay hand-written: a one-line summary, `##` sections, and a
+closing `**Full Changelog**:` compare link.
+
 ### Build hook
 `hatch_build.py` generates `.pyi` type stubs via `mypy stubgen` at build time and
 force-includes them in the wheel (they are gitignored). `mx_remote` ships as typed

{mx_remote-5.6.0 → mx_remote-5.8.0}/PKG-INFO

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

@@ -14,6 +14,9 @@ if device.is_v2ip and device.v2ip_sources:
         print(f"Audio: {source.audio.ip}:{source.audio.port}")
 
 # stream details (encoder/decoder config)
+# A configuration frame names its subject in the payload, so a controller's
+# write for a transceiver reaches the transceiver's record - the controller's
+# own stays empty, which is what the device always meant.
 if device.v2ip_details:
     details = device.v2ip_details
     print(f"Video: {details.video}")
@@ -91,6 +94,71 @@ reading from a repeat, and note it cannot see a `TX_BRIDGE_UNLOCKED` flag
 carried forward across a format change: a value held over is a stored reading
 like any other.
 
+## Sink output scaling
+
+A sink scales for two independent reasons: automatic scaling, and a configured
+output mode. Each is written behind its own validity bit, so moving one leaves
+the other where it is.
+
+```python
+# what the sink reports. Trust this block only from a device whose hello carries
+# CONFIG_INITIALISED - firmware without it builds the block over uninitialised
+# stack, where the valid bit itself is noise.
+scaling = device.v2ip_details.scaling
+print(scaling.auto_scaling)        # None when the sender did not say
+print(scaling.configured_mode)     # (signal type, refresh), None when it has none
+
+# a mode is given as a depth and a colour space, never as a packed signal-type
+# word read back off the wire: a sink with no mode reports the word carrying the
+# index for "no depth", which a receiver decodes to zero and drops in silence.
+mode = mx_remote.V2IPOutputMode(svd=16, depth=12,
+                                colour=mx_remote.VideoColourSpace.YUV422, refresh=60)
+
+await device.set_v2ip_auto_scaling(False)   # turn it off before setting a mode
+await device.set_v2ip_output_mode(mode)
+await device.set_v2ip_auto_scaling(True)    # back on, if that is what you want
+
+await device.clear_v2ip_output_mode()       # the only way to say "no mode"
+```
+
+**Set the mode with automatic scaling off.** A sink scaling automatically
+refuses a mode whose format the attached display does not list, and refuses it
+in silence. Setting the mode first and turning automatic scaling back on
+afterwards is the order that survives, because the mode is checked while
+automatic scaling is still off.
+
+Nothing acknowledges any of these. `set_v2ip_output_mode` returns False for a
+mode no sink would take, but a True only says the frame went out: the sink
+weighs the format against the display's EDID and against what its own output
+stage can produce, and refuses silently either way. Read `v2ip_details.scaling`
+back on the device's next report to learn what it did.
+
+A scaling change makes the device rebuild and rebroadcast its sink block, so
+expect `device.v2ip_sink` to read empty for a moment afterwards - see
+[what an empty sink block means](#what-an-empty-sink-block-means).
+
+## What an empty sink block means
+
+`device.v2ip_sink` addresses that read as unset mean "no route, or the sink
+could not work one out", never "definitely not subscribed". This is the one part
+of a device configuration with no validity marker of its own, so a sender with
+nothing to say sends zeros and every receiver stores them. A sender leaves it
+empty whenever its own stream configuration does not resolve, which covers more
+than having no route: a selected source whose record has not arrived yet, the
+state after a restart at either end, missing audio bay configuration, or a
+stream failing its validity check.
+
+Expect that reading rather than guarding against it. Any scaling change rebuilds
+and rebroadcasts the block, and a write aimed at a remote bay sends it zeroed
+however it was requested, so an empty reading turns up most often during exactly
+the no-signal troubleshooting that prompted the change. A device's periodic
+report puts a real route back within a minute of it having one, so wait one out
+rather than treat the first empty reading as an answer.
+
+The library caches an empty reading rather than dropping it. A sink that has
+genuinely lost its route sends the same zeros, and so does every report after
+it, so refusing them would hold a route that nothing later could clear.
+
 ## Mesh and firmware
 
 ```python

{mx_remote-5.6.0 → mx_remote-5.8.0}/mx_remote/Interface.py

@@ -28,7 +28,7 @@ from .proto.Multiviewer import (
 	MultiviewerITCMode,
 	MultiviewerHDCPMode,
 )
-from .proto.Svd import SvdMap
+from .proto.Svd import SvdMap, lookup_svd
 from typing import Any, Callable
 from .Uid import MxrDeviceUid, MxrBayUid
 
@@ -1390,6 +1390,28 @@ class DeviceV2IPScalingSettings(ABC):
         is the only option bit with a defined meaning.
         '''
 
+    @property
+    def configured_mode(self) -> 'tuple[MxrSignalType, int]|None':
+        '''The mode and refresh rate this sink scales to, None when it has none.
+
+        The two are distinct on the wire: a sink with no mode configured leaves
+        MXR_SCALING_FLAG_MODE_VALID clear, and never sets it over a zero mode.
+
+        Trust it only from a peer whose hello carries CONFIG_INITIALISED
+        (DeviceBase.config_initialised). Firmware without that builds this block
+        over uninitialised stack, where the valid bit itself is noise.
+        '''
+        if ((self.flags & MXR_SCALING_FLAG_MODE_VALID) == 0):
+            return None
+        return (MxrSignalType(self.mode.to_bytes(2, 'little')), self.refresh)
+
+    @property
+    def auto_scaling(self) -> bool|None:
+        '''Whether the output scales automatically, None when the sender did not say.'''
+        if ((self.flags & MXR_SCALING_FLAG_OPTIONS_VALID) == 0):
+            return None
+        return ((self.flags & MXR_SCALING_FLAG_AUTO_SCALING) != 0)
+
 def v2ip_stream_valid(stream:'V2IPStreamSource|None') -> bool:
     """
     True when a stream source carries an address a frame actually meant to send.
@@ -1418,6 +1440,72 @@ def v2ip_stream_cleared(stream:'V2IPStreamSource|None') -> bool:
     """True when a stream source is zeroed, which is how "no source" is spelled."""
     return (stream is not None) and (stream.ip == '0.0.0.0') and (stream.port == 0)
 
+class V2IPOutputMode:
+    """
+    The output format to scale a V2IP sink to.
+
+    Built from a depth and a colour space rather than from a packed
+    mxr_signal_type word, so the word a caller sends cannot carry the unset bpp
+    index a sink reports while it has no mode configured.
+    """
+    def __init__(self, svd:int, depth:int, colour:VideoColourSpace, refresh:int) -> None:
+        self.svd = svd
+        """CTA-861 short video descriptor to output."""
+        self.depth = depth
+        """Bit depth: 8, 10 or 12."""
+        self.colour = colour
+        """Colour space to output."""
+        self.refresh = refresh
+        """Refresh rate in Hz, V2IP_SCALING_REFRESH_MIN to V2IP_SCALING_REFRESH_MAX."""
+
+    def validate(self) -> str|None:
+        """
+        Why a sink will refuse this mode, or None when it will take it.
+
+        Checked here because a sink checks it and then says nothing: every value
+        this rejects is one the receiver decodes cleanly and drops, leaving a
+        caller with a send that succeeded and a setting that did not move.
+
+        Passing is not a guarantee. A sink also weighs the format against the
+        EDID of the display attached to it and against what its own clock and
+        output stage can produce, and none of that is knowable from here.
+        """
+        if (self.svd == 0):
+            return "svd 0 is how a mode is cleared, not a mode to set"
+        if (lookup_svd(self.svd) is None):
+            return "the svd names no known video descriptor"
+        if (mxr_sig_bpp_index(self.depth) is None):
+            return "a V2IP output stage takes 8, 10 or 12 bits per pixel"
+        if (self.colour not in (VideoColourSpace.RGB, VideoColourSpace.YUV444,
+                                VideoColourSpace.YUV422, VideoColourSpace.YUV420)):
+            return "the colour space names none of RGB, 4:4:4, 4:2:2 or 4:2:0"
+        if not (V2IP_SCALING_REFRESH_MIN <= self.refresh <= V2IP_SCALING_REFRESH_MAX):
+            return f"the refresh rate is outside {V2IP_SCALING_REFRESH_MIN}..{V2IP_SCALING_REFRESH_MAX}Hz"
+        return None
+
+    @property
+    def signal_type(self) -> MxrSignalType:
+        """
+        The packed signal type a scaling write carries for this mode.
+
+        Call validate() first: an unvalidated depth packs as the index for
+        "no depth", which a receiver drops.
+        """
+        return MxrSignalType.from_parts(svd=self.svd, colour=int(self.colour),
+                                        bpp_index=(mxr_sig_bpp_index(self.depth) or 0))
+
+    def __eq__(self, other:Any) -> bool:
+        if not isinstance(other, V2IPOutputMode):
+            return NotImplemented
+        return (self.svd == other.svd) and (self.depth == other.depth) \
+            and (self.colour == other.colour) and (self.refresh == other.refresh)
+
+    def __str__(self) -> str:
+        return f"svd {self.svd}, colour {self.colour}, {self.depth}bpp, {self.refresh}Hz"
+
+    def __repr__(self) -> str:
+        return str(self)
+
 class V2IPScalingSettings(DeviceV2IPScalingSettings):
     """Plain holder for a merged mxr_scaling_config."""
     def __init__(self, mode:int, refresh:int, flags:int) -> None:
@@ -1627,6 +1715,28 @@ class DeviceV2IPSink:
     when present, each stream may still carry an all-zero ip when that stream is
     inactive. ``audio_fmt`` carries the resolved sink audio format (zero fields
     fall back to firmware defaults of 48kHz / 2 channels).
+
+    **An address that reads as unset means "no route, or the sink could not work
+    one out", never "definitely not subscribed".** This block is the one part of
+    a device configuration with no validity marker of its own, so a sender with
+    nothing to say sends zeros and every receiver stores them. A sender leaves it
+    empty whenever its own stream configuration does not resolve, which covers
+    more than having no route: a selected source whose record has not arrived
+    yet, the state after a restart at either end, missing audio bay
+    configuration, or a stream failing its validity check. ``audio_fmt`` has a
+    second gate of its own, so it can be absent while the addresses are not.
+
+    Expect that reading rather than guarding against it. Any scaling change makes
+    the device rebuild and rebroadcast this block, and a write aimed at a remote
+    bay sends it zeroed however it was requested, so an empty reading turns up
+    most often during exactly the no-signal troubleshooting that prompted the
+    change. A device's periodic report puts a real route back within a minute of
+    it having one, so a reader that needs certainty should wait one out rather
+    than treat the first empty reading as an answer.
+
+    An empty reading is cached rather than dropped on purpose. A sink that has
+    genuinely lost its route sends the same zeros, and so does every report after
+    it, so refusing them would hold a route that nothing later could clear.
     """
     def __init__(self, addresses:V2IPStreamSources|None, audio_fmt:V2IPAudioFormat|None) -> None:
         self._addresses = addresses
@@ -1956,6 +2066,17 @@ class DeviceBase(ABC):
     def mesh_master(self, master:MxrDeviceUid) -> None:
         '''Change the master device of this device'''
 
+    @property
+    @abstractmethod
+    def mesh_master_uid(self) -> MxrDeviceUid|None:
+        '''UID of the mesh controller this device reports, None while it has named none.
+
+        Distinct from mesh_master, which falls back to the device itself. A
+        device that has named no controller is not a device that follows nobody:
+        a client that has just started knows nothing about anyone for as long as
+        a broadcast period.
+        '''
+
     @property
     @abstractmethod
     def protocol(self) -> int:
@@ -1978,6 +2099,31 @@ class DeviceBase(ABC):
     def is_mesh_master(self) -> bool:
         '''True if this device is the master device of a V2IP mesh'''
 
+    @property
+    @abstractmethod
+    def is_management(self) -> bool:
+        '''True when a receiver would let this device write another device's configuration.
+
+        Two bits, because the two kinds of writer announce themselves
+        differently and neither implies the other. MANAGER belongs to external
+        management applications - anything driving these devices that is not one
+        of them, this library included - and no device firmware ever sets it on
+        itself, so testing it alone would refuse every write a controller makes.
+        A device that is controlling its mesh announces MESH_MASTER instead.
+
+        The bits have a hole a caller has to close elsewhere: a device sets
+        MESH_MASTER only while it is both the controller and has bays mapped, so
+        one promoted before it has any carries neither bit while still being its
+        mesh's controller. What covers that window is the controller uid the
+        devices in that mesh report, which is their question rather than this
+        device's - see mesh_master_uid.
+        '''
+
+    @property
+    @abstractmethod
+    def is_v2ip_sink(self) -> bool:
+        '''True if this device decodes a V2IP stream, which is what carries the scaling settings'''
+
     @property
     @abstractmethod
     def is_mesh_member(self) -> bool:
@@ -2106,6 +2252,18 @@ class DeviceBase(ABC):
     async def read_stats(self, enable:bool) -> bool:
         '''start or stop dumping stats'''
 
+    @abstractmethod
+    async def set_v2ip_auto_scaling(self, enabled:bool) -> bool:
+        '''turn this sink's automatic scaling on or off'''
+
+    @abstractmethod
+    async def set_v2ip_output_mode(self, mode:'V2IPOutputMode') -> bool:
+        '''set the output format this sink scales to'''
+
+    @abstractmethod
+    async def clear_v2ip_output_mode(self) -> bool:
+        '''clear the output format this sink is configured to scale to'''
+
     @abstractmethod
     async def get_log(self) -> str|None:
         '''read the log from the device and return it as string'''

{mx_remote-5.6.0 → mx_remote-5.8.0}/mx_remote/Interface.pyi

@@ -4,7 +4,7 @@ from .Uid import MxrBayUid as MxrBayUid, MxrDeviceUid as MxrDeviceUid
 from .proto import RCKey as RCKey
 from .proto.Data import VolumeMuteStatus as VolumeMuteStatus
 from .proto.Multiviewer import MultiviewerAspectRatio as MultiviewerAspectRatio, MultiviewerBoolSetting as MultiviewerBoolSetting, MultiviewerEDIDTemplate as MultiviewerEDIDTemplate, MultiviewerHDCPMode as MultiviewerHDCPMode, MultiviewerITCMode as MultiviewerITCMode, MultiviewerOutputMode as MultiviewerOutputMode, MultiviewerPipPosition as MultiviewerPipPosition, MultiviewerPipSize as MultiviewerPipSize, MultiviewerSource as MultiviewerSource, MultiviewerViewMode as MultiviewerViewMode
-from .proto.Svd import SvdMap as SvdMap
+from .proto.Svd import SvdMap as SvdMap, lookup_svd as lookup_svd
 from .proto.V2IPStats import V2IPDeviceStats as V2IPDeviceStats
 from _typeshed import Incomplete
 from abc import ABC, abstractmethod
@@ -582,11 +582,26 @@ class DeviceV2IPScalingSettings(ABC):
     @property
     @abstractmethod
     def flags(self) -> int: ...
+    @property
+    def configured_mode(self) -> tuple[MxrSignalType, int] | None: ...
+    @property
+    def auto_scaling(self) -> bool | None: ...
 
 def v2ip_stream_valid(stream: V2IPStreamSource | None) -> bool: ...
 def v2ip_av_source_valid(video: V2IPStreamSource | None, anc: V2IPStreamSource | None) -> bool: ...
 def v2ip_stream_cleared(stream: V2IPStreamSource | None) -> bool: ...
 
+class V2IPOutputMode:
+    svd: Incomplete
+    depth: Incomplete
+    colour: Incomplete
+    refresh: Incomplete
+    def __init__(self, svd: int, depth: int, colour: VideoColourSpace, refresh: int) -> None: ...
+    def validate(self) -> str | None: ...
+    @property
+    def signal_type(self) -> MxrSignalType: ...
+    def __eq__(self, other: Any) -> bool: ...
+
 class V2IPScalingSettings(DeviceV2IPScalingSettings):
     def __init__(self, mode: int, refresh: int, flags: int) -> None: ...
     @property
@@ -825,6 +840,9 @@ class DeviceBase(ABC):
     def mesh_master(self, master: MxrDeviceUid) -> None: ...
     @property
     @abstractmethod
+    def mesh_master_uid(self) -> MxrDeviceUid | None: ...
+    @property
+    @abstractmethod
     def protocol(self) -> int: ...
     @abstractmethod
     def supports_opcode(self, opcode: int) -> bool: ...
@@ -833,6 +851,12 @@ class DeviceBase(ABC):
     def is_mesh_master(self) -> bool: ...
     @property
     @abstractmethod
+    def is_management(self) -> bool: ...
+    @property
+    @abstractmethod
+    def is_v2ip_sink(self) -> bool: ...
+    @property
+    @abstractmethod
     def is_mesh_member(self) -> bool: ...
     @property
     @abstractmethod
@@ -899,6 +923,12 @@ class DeviceBase(ABC):
     @abstractmethod
     async def read_stats(self, enable: bool) -> bool: ...
     @abstractmethod
+    async def set_v2ip_auto_scaling(self, enabled: bool) -> bool: ...
+    @abstractmethod
+    async def set_v2ip_output_mode(self, mode: V2IPOutputMode) -> bool: ...
+    @abstractmethod
+    async def clear_v2ip_output_mode(self) -> bool: ...
+    @abstractmethod
     async def get_log(self) -> str | None: ...
     @abstractmethod
     def on_mxr_update(self, data: object) -> None: ...

{mx_remote-5.6.0 → mx_remote-5.8.0}/mx_remote/const.py

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

{mx_remote-5.6.0 → mx_remote-5.8.0}/mx_remote/proto/Constants.py

@@ -146,6 +146,12 @@ MXR_SCALING_FLAG_AUTO_SCALING  = (1 << 7)
 """mxr_scaling_config.flags. The mode/refresh pair and the options nibble are
 separately valid: a sender carrying neither flag is offering no scaling at all."""
 
+V2IP_SCALING_REFRESH_MIN = 24
+V2IP_SCALING_REFRESH_MAX = 120
+"""Refresh rate range a V2IP output stage accepts, in Hz. A receiver replaces
+anything outside it with 50 rather than refusing the write, so a 0 here asks
+for 50Hz instead of asking for nothing."""
+
 MXR_V2IP_DSCP_SET = 0x80
 """DSCP 0 (CS0) is a legal marking, so a zero byte cannot mean "absent": each
 dscp byte in a V2IP_DEVICE_CFG options word carries this bit alongside its
@@ -379,6 +385,23 @@ def mxr_sig_bpp_get(bpp: int) -> int:
 	bit depth is a common trap. Returns 0 for both unknown and unset.'''
 	return _MXR_SIG_BPP_VALUES.get(bpp, MXR_SIG_BPP_UNKNOWN)
 
+_MXR_SIG_BPP_WRITABLE_INDICES: dict[int, int] = {
+	8:  1,
+	10: 2,
+	12: 3,
+}
+
+def mxr_sig_bpp_index(depth: int) -> int|None:
+	'''Map a bit depth to the mxr_signal_type bpp *index* that stands for it.
+
+	Only the three depths a V2IP output stage accepts are here. Index 4 names
+	16bpp, which mxr_sig_bpp_get() reads back from a device, but the output
+	stage refuses it - offering it as something to write would build a frame
+	that is decoded cleanly and then dropped in silence.
+
+	Returns None for a depth no index names.'''
+	return _MXR_SIG_BPP_WRITABLE_INDICES.get(depth)
+
 class MxrSignalType:
 	'''The 2-byte mxr_signal_type carried in scaling configs and bay signal reports.
 
@@ -391,6 +414,26 @@ class MxrSignalType:
 		self._svd = int(data[0])
 		self._flags = int(data[1])
 
+	@staticmethod
+	def from_parts(svd: int, colour: int, bpp_index: int) -> 'MxrSignalType':
+		'''Build the word a scaling write carries, from the fields it consumes.
+
+		non_int is left clear: the receiving struct carries the bit and the
+		apply path does not read it.
+
+		Building rather than editing is the point. A sink with no mode
+		configured reports the word with the unset bpp index in it, so a caller
+		that read that word back and filled in an svd would send an index no
+		depth uses, which the receiver decodes to zero and rejects without
+		answering.'''
+		flags = (colour & 0xF) | ((bpp_index & 0x7) << 5)
+		return MxrSignalType(bytes([svd & 0xFF, flags]))
+
+	@property
+	def byte_value(self) -> bytes:
+		'''The two bytes as they sit on the wire.'''
+		return bytes([self._svd, self._flags])
+
 	@property
 	def value(self) -> int:
 		'''Raw 16-bit value.'''

{mx_remote-5.6.0 → mx_remote-5.8.0}/mx_remote/proto/Constants.pyi

@@ -18,6 +18,8 @@ def v2ip_rate_valid(rate: int | None) -> bool: ...
 MXR_SCALING_FLAG_MODE_VALID: Incomplete
 MXR_SCALING_FLAG_OPTIONS_VALID: Incomplete
 MXR_SCALING_FLAG_AUTO_SCALING: Incomplete
+V2IP_SCALING_REFRESH_MIN: int
+V2IP_SCALING_REFRESH_MAX: int
 MXR_V2IP_DSCP_SET: int
 V2IP_DSCP_MAX: int
 V2IP_DSCP_DEFAULT: int
@@ -108,9 +110,14 @@ MXR_SIG_BPP_UNKNOWN: int
 MXR_SIG_BPP_UNSET: int
 
 def mxr_sig_bpp_get(bpp: int) -> int: ...
+def mxr_sig_bpp_index(depth: int) -> int | None: ...
 
 class MxrSignalType:
     def __init__(self, data: bytes) -> None: ...
+    @staticmethod
+    def from_parts(svd: int, colour: int, bpp_index: int) -> MxrSignalType: ...
+    @property
+    def byte_value(self) -> bytes: ...
     @property
     def value(self) -> int: ...
     @property

{mx_remote-5.6.0 → mx_remote-5.8.0}/mx_remote/proto/FrameV2IPDeviceConfiguration.py

@@ -7,12 +7,15 @@
 '''Protocol frame for V2IP device configuration (stream addresses, scaling, options).'''
 
 from functools import cached_property
+from typing import Any
 from .FrameBase import FrameBase
 from .FrameHeader import FrameHeader
 from ..Uid import MxrDeviceUid
-from ..Interface import DeviceV2IPDetails, DeviceV2IPScalingSettings, DeviceV2IPSink, V2IPAudioFormat, V2IPDscpConfig, V2IPStreamSource
+from ..Interface import (DeviceBase, DeviceRegistry, DeviceV2IPDetails, DeviceV2IPScalingSettings,
+                         DeviceV2IPSink, V2IPAudioFormat, V2IPDscpConfig, V2IPStreamSource)
 from .Constants import (MXR_SCALING_FLAG_AUTO_SCALING, MXR_SCALING_FLAG_MODE_VALID,
-                        MXR_SCALING_FLAG_OPTIONS_VALID, v2ip_dscp_value, v2ip_rate_valid)
+                        MXR_SCALING_FLAG_OPTIONS_VALID, MxrSignalType, v2ip_dscp_value,
+                        v2ip_rate_valid)
 from .V2IPConfig import V2IPStreamSourceImpl, parse_v2ip_av_source
 
 # v2ip_device_config_update wire layout (little-endian, ALIGN(8) per inner struct):
@@ -120,6 +123,15 @@ class V2IPScalingSettingsImpl(DeviceV2IPScalingSettings):
     def flags(self) -> int:
         return self._flags
 
+_OPCODE = 0x3C
+
+_RATE_UNSET = 0xFF
+'''The tx_rate a frame that is not setting a rate carries.
+
+The field's valid range ends at V2IP_SOURCE_RATE_MAX, and a receiver drops an
+out-of-range rate and keeps the one it had. A plain zero would ask for a rate of
+zero.'''
+
 class FrameV2IPDeviceConfiguration(FrameBase):
     '''V2IP device configuration with stream addresses and scaling settings.'''
     def __init__(self, header:FrameHeader, timestamp:float):
@@ -133,6 +145,57 @@ class FrameV2IPDeviceConfiguration(FrameBase):
         self.arc = V2IPStreamSourceImpl("arc", self.payload[48:54])
         self.scaling = V2IPScalingSettingsImpl(self.payload[56:61])
 
+    @staticmethod
+    def construct_scaling(mxr:DeviceRegistry, target:Any, target_uid:MxrDeviceUid,
+                          mode:MxrSignalType, refresh:int, flags:int) -> FrameBase|None:
+        '''Build the 0x3C write that moves one sink's scaling block and nothing else.
+
+        88 bytes, which is both the receiver's minimum and the whole of
+        v2ip_device_config_update: uid 0..16, source 16..40, the options word at
+        40, audio return 48..56, scaling 56..64, tiling 64..88.
+
+        **88 rather than the 120-byte form.** The longer form appends a sink
+        block, and a receiver copies that block into its record for the target
+        with no validity test of its own - unlike the source, rate, marking,
+        scaling and tiling fields, which each sit behind one. This frame is a
+        broadcast, so every device on the network runs that copy, not just the
+        addressee: sending the long form with the block zeroed would replace the
+        whole network's idea of where the target's sink is subscribed, as a side
+        effect of setting one scaling flag. At 88 the block is absent rather
+        than zeroed and nothing reads it.
+
+        **The source block at 16..40 must stay zeroed**, and does. A receiver
+        hands this frame's addresses to its encoder unconditionally, on every
+        frame it applies rather than only on the ones that carry addresses; what
+        stops a scaling write from repointing the encoder is that the call
+        refuses a video address which is not multicast. Zero is not multicast.
+        Anything that is, written here, would move a transceiver's stream.
+
+        Which halves of the scaling block a receiver reads is chosen by the
+        validity bits in flags, not by this layout: the mode and refresh are
+        read behind MXR_SCALING_FLAG_MODE_VALID and the options behind
+        MXR_SCALING_FLAG_OPTIONS_VALID, so a write that carries neither bit
+        lands as a no-op rather than as a request to zero the settings.
+        '''
+        payload = bytearray(target_uid.byte_value)
+        if (len(payload) != 16):
+            raise ValueError(f"invalid uid length: {len(payload)}")
+        # source: three stream slots, left zeroed so the encoder keeps its own.
+        payload += bytes(40 - len(payload))
+        payload.append(_RATE_UNSET)
+        # Three dscp bytes with no MXR_V2IP_DSCP_SET bit, so no marking is
+        # applied, then the padding that aligns the audio-return slot, then the
+        # audio return itself, zeroed, which reads as carrying no address.
+        payload += bytes(56 - len(payload))
+        payload += mode.byte_value
+        payload += refresh.to_bytes(2, 'little')
+        payload.append(flags & 0xFF)
+        # The scaling struct is 8-aligned, so its five bytes of fields are
+        # followed by three of padding; then the tiling window, whose zero uid
+        # is what says no window is carried.
+        payload += bytes(_BASE_SIZE - len(payload))
+        return FrameBase.construct_base(target=target, mxr=mxr, opcode=_OPCODE, payload=bytes(payload))
+
     @property
     def target_uid(self) -> MxrDeviceUid|None:
         return self.payload_uuid(idx=0)
@@ -141,6 +204,43 @@ class FrameV2IPDeviceConfiguration(FrameBase):
     def target_self(self) -> bool:
         return (self.remote_id == self.target_uid)
 
+    @cached_property
+    def subject_device(self) -> DeviceBase|None:
+        '''The device this configuration is about, None when nothing would act on it.
+
+        The payload names its subject in the first sixteen bytes, and that is
+        what decides whose configuration this is - not who sent it. Equal to the
+        sender it is a device describing itself, which is what almost every one
+        of these frames is. Different, it is a write for the device it names,
+        and a receiver takes one only from a sender it treats as management.
+        Anything else is dropped rather than filed against the sender, because a
+        frame the network ignores must not move a record here.
+        '''
+        if ((subject := self.target_uid) is None):
+            return None
+        if (subject == self.remote_id):
+            return self.remote_device
+        # An unknown subject is dropped, as it is on a device: there is no
+        # record to move, and inventing one from a third party's description
+        # would create a device nothing has been heard from.
+        if ((device := self.mxr.get_by_uid(subject)) is None):
+            return None
+        sender = self.remote_device
+        if ((sender is not None) and sender.is_management):
+            return device
+        # Or the subject naming this sender as its mesh controller. Asked of the
+        # subject rather than the sender because it closes the window where a
+        # controller has been promoted but has no bays mapped yet, and so
+        # announces neither bit while still being the controller its mesh obeys.
+        #
+        # A subject that has named no controller contributes nothing here rather
+        # than refusing: not knowing who a device follows is not knowing that it
+        # follows nobody, and a client that has just started knows nothing about
+        # anyone for as long as a broadcast period.
+        if (device.mesh_master_uid == self.remote_id):
+            return device
+        return None
+
     @cached_property
     def details(self) -> DeviceV2IPDetails:
         return DeviceV2IPDetails(video=self.video, audio=self.audio, anc=self.anc, arc=self.arc, tx_rate=self.options.tx_rate, scaling=self.scaling, dscp=self.options.dscp)
@@ -156,8 +256,8 @@ class FrameV2IPDeviceConfiguration(FrameBase):
         )
 
     def process(self) -> None:
-        '''Update the local device cache with V2IP configuration details.'''
-        if ((dev := self.remote_device) is None):
+        '''Update the cache of the device this configuration names, not of its sender.'''
+        if ((dev := self.subject_device) is None):
             return
         dev.on_mxr_update(self.details)
         if ((sink := self.sink) is not None):

{mx_remote-5.6.0 → mx_remote-5.8.0}/mx_remote/proto/FrameV2IPDeviceConfiguration.pyi

@@ -1,11 +1,12 @@
-from ..Interface import DeviceV2IPDetails as DeviceV2IPDetails, DeviceV2IPScalingSettings as DeviceV2IPScalingSettings, DeviceV2IPSink as DeviceV2IPSink, V2IPAudioFormat as V2IPAudioFormat, V2IPDscpConfig as V2IPDscpConfig, V2IPStreamSource as V2IPStreamSource
+from ..Interface import DeviceBase as DeviceBase, DeviceRegistry as DeviceRegistry, DeviceV2IPDetails as DeviceV2IPDetails, DeviceV2IPScalingSettings as DeviceV2IPScalingSettings, DeviceV2IPSink as DeviceV2IPSink, V2IPAudioFormat as V2IPAudioFormat, V2IPDscpConfig as V2IPDscpConfig, V2IPStreamSource as V2IPStreamSource
 from ..Uid import MxrDeviceUid as MxrDeviceUid
-from .Constants import 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, v2ip_dscp_value as v2ip_dscp_value, v2ip_rate_valid as v2ip_rate_valid
+from .Constants import 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, v2ip_dscp_value as v2ip_dscp_value, v2ip_rate_valid as v2ip_rate_valid
 from .FrameBase import FrameBase as FrameBase
 from .FrameHeader import FrameHeader as FrameHeader
 from .V2IPConfig import V2IPStreamSourceImpl as V2IPStreamSourceImpl, parse_v2ip_av_source as parse_v2ip_av_source
 from _typeshed import Incomplete
 from functools import cached_property
+from typing import Any
 
 class V2IPDeviceOptions:
     def __init__(self, data: bytes) -> None: ...
@@ -33,11 +34,15 @@ class FrameV2IPDeviceConfiguration(FrameBase):
     arc: Incomplete
     scaling: Incomplete
     def __init__(self, header: FrameHeader, timestamp: float) -> None: ...
+    @staticmethod
+    def construct_scaling(mxr: DeviceRegistry, target: Any, target_uid: MxrDeviceUid, mode: MxrSignalType, refresh: int, flags: int) -> FrameBase | None: ...
     @property
     def target_uid(self) -> MxrDeviceUid | None: ...
     @property
     def target_self(self) -> bool: ...
     @cached_property
+    def subject_device(self) -> DeviceBase | None: ...
+    @cached_property
     def details(self) -> DeviceV2IPDetails: ...
     @cached_property
     def sink(self) -> DeviceV2IPSink | None: ...