mx-remote 5.5.1__tar.gz → 5.7.0__tar.gz

{mx_remote-5.5.1 → mx_remote-5.7.0}/.gitignore

@@ -1,5 +1,6 @@
 __pycache__
 /build
 /dist
+/site
 *.egg-info
 *.pyi

{mx_remote-5.5.1 → mx_remote-5.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mx_remote
-Version: 5.5.1
+Version: 5.7.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.7.0/docs/oneip.md

@@ -0,0 +1,177 @@
+# OneIP and V2IP
+
+Streaming endpoints, stream sources and statistics.
+
+## Pulse-Eight OneIP Devices
+
+[Pulse-Eight OneIP](https://www.pulse-eight.com/p/248/oneip-tx) HDMI-over-IP devices expose additional streaming properties:
+
+```python
+# stream source addresses
+if device.is_v2ip and device.v2ip_sources:
+    for source in device.v2ip_sources:
+        print(f"Video: {source.video.ip}:{source.video.port}")
+        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}")
+    print(f"TX rate: {details.tx_rate}")   # None when the sender offered no rate
+
+    # per-stream DSCP marking (None from peers that predate it)
+    if details.dscp and details.dscp.complete:
+        print(f"DSCP: {details.dscp}")     # video / audio / anc, 0..63
+
+# streaming statistics
+# The subscription lapses 60s after the request and there is no free-running
+# mode, so call this again inside the minute to keep the 1Hz reports coming.
+await device.read_stats(enable=True)   # start collecting
+# ... later ...
+stats = device.v2ip_stats
+
+# what the sink's decoder recovered from the codestream it is being given.
+# Three answers, and they mean different things:
+if stats.decoder is None:
+    pass                                  # sender predates MatrixOS 10.12.46
+elif stats.decoder.reading is None:
+    pass                                  # decoder has never answered
+else:
+    reading = stats.decoder.reading
+    # Geometry is what says a picture was recovered. `format` never does: with
+    # no stream it reads RGB, which is indistinguishable from a real RGB source.
+    if reading.recovered:
+        print(f"{reading.width}x{reading.height} {reading.format}")
+    # `reason` for display, `causes` for logic. Every true cause sets its bit
+    # in flags; which one keeps `reason` is a fixed priority in the video
+    # processor, not the numbering. TX_BRIDGE_UNLOCKED ranks below every
+    # input-side cause, so a repeating pipeline restart shows as bit 9 in
+    # `causes` while `reason` names the input cause instead.
+    print(f"{reading.reason}")            # None for a cause this build cannot name
+    print(f"{reading.causes}")            # raw reason values, lowest first
+```
+
+### Trusting a decoder reading after a switch
+
+The values are read off the video processor every 2s and reported every 1s,
+latched between reads, so roughly every other report repeats a reading already
+seen — a frame arriving says nothing about freshness. `reading.updates` counts
+readings actually **stored**, so it stays still while a processor is stalled
+rather than implying a refresh. It is monotonic, never reset, and wraps at
+65535 (~36h).
+
+After changing what a sink is pointed at, wait for `updates` to advance by
+**two** before trusting the geometry. It ticks when the reply lands, not when
+the query is sent, so a single tick can carry an answer read fractionally
+before the switch.
+
+```python
+before = device.v2ip_stats.decoder.reading.updates
+await sink.switch_source(...)
+# ... wait until reading.updates - before >= 2 (mod 65536) ...
+```
+
+Colour depth is deliberately absent: the video processor answers depth from a
+driver constant rather than from the codestream, so it was withheld rather than
+shipped as a constant that looks like a measurement. Assert depth at the
+encoder's input bay instead.
+
+### What this block cannot tell you
+
+**Whether a sink is off on purpose.** A sink someone deliberately disabled
+reports `NO_PACKETS`, indefinitely — the same cause as a sink that should be
+receiving and is not. There is no enablement field here, so read that from
+`MXR_OP_V2IP_DEVICE_CFG` or the device's HTTP status. `IDLE` sounds like the
+answer and is not: it is effectively unreachable in shipping firmware.
+
+**Whether a single sample is representative.** `reason` during a teardown is a
+sequence, not a state — a measured one passed through `SWITCH_PENDING` before
+settling on `NO_PACKETS` six seconds later. Use `updates` to tell a fresh
+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
+# mesh operations
+await device.mesh_promote()   # promote to mesh master
+await device.mesh_remove()    # remove from mesh
+
+# firmware versions
+if device.v2ip_firmware_versions:
+    for fw_type, fw in device.v2ip_firmware_versions.items():
+        print(f"{fw_type}: {fw.version}")
+```
+
+---
+
+[Documentation index](README.md) | [Project README](https://github.com/opdenkamp/mx-remote#readme)

{mx_remote-5.5.1 → mx_remote-5.7.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.5.1 → mx_remote-5.7.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.5.1 → mx_remote-5.7.0}/mx_remote/const.py

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

{mx_remote-5.5.1 → mx_remote-5.7.0}/mx_remote/proto/Constants.py

@@ -10,13 +10,18 @@
 from enum import IntEnum, IntFlag
 from typing import TypeVar
 
-MXR_PROTOCOL_VERSION = 0x28
+MXR_PROTOCOL_VERSION = 0x29
 """Highest mx_remote protocol version this library understands.
 
 Mirrors the firmware's own protocol version. Bump
 when adding RX support for an opcode revision; transmitters stamp the
 per-opcode minimum from MXR_OPCODE_VERSIONS so older peers still parse the
-frame."""
+frame.
+
+This is also a receive ceiling: Remote.process_frame drops any frame stamped
+above it, unparsed. So it has to reach the stamp of every layout revision
+decoded below, or that revision goes silent on the mesh rather than noisy -
+0x29 is what a MatrixOS 10.12.46 unit stamps on V2IP_STATS."""
 
 MXR_OPCODE_VERSIONS: dict[int, int] = {
     0x00: 0x01,  # SYS_HELLO
@@ -141,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
@@ -374,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.
 
@@ -386,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.5.1 → mx_remote-5.7.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.5.1 → mx_remote-5.7.0}/mx_remote/proto/FrameFactoryReset.py

@@ -7,10 +7,15 @@
 '''Protocol frame for SYS_FACTORY_RESET (opcode 0x3A).
 
 A mesh controller or management app broadcasts this to factory-reset peers.
-Payload variants the firmware accepts:
-    empty           controller-only target (just the sender)
-    1 byte = 0xFF   broadcast to all peers (controller/management only)
-    16 bytes        single target uid
+Payload forms:
+    empty            controller-only target (just the sender)
+    >=1, byte 0xFF   broadcast to all peers (controller/management only)
+    >=16             single target uid
+
+Each length is a minimum and they are tested longest first. An update that
+appends a field leaves the fields ahead of it where they are, so an exact
+length would read a grown request as a shorter form - here, as one addressing
+nobody.
 '''
 
 from functools import cached_property
@@ -22,11 +27,21 @@ class FrameFactoryReset(FrameBase):
 
     @cached_property
     def is_broadcast_all(self) -> bool:
-        return (len(self) == 1) and (self.payload_u8(0) == 0xFF)
+        '''Whether this asks every peer to reset.
+
+        Tested after the uid form, which is longer: a uid whose first byte is
+        0xFF would otherwise read as a broadcast.'''
+        return (self.target_uid is None) and (len(self) >= 1) and (self.payload_u8(0) == 0xFF)
 
     @cached_property
     def target_uid(self) -> MxrDeviceUid | None:
-        if (len(self) == 16):
+        '''Uid of the single peer being reset, None when the request names none.
+
+        A minimum rather than an exact length. A sender that appends a field
+        leaves the uid where it is, so requiring 16 exactly would read a grown
+        request as one addressing nobody - which is the sender resetting itself,
+        a different request altogether.'''
+        if (len(self) >= 16):
             return self.payload_uuid(0)
         return None
 

{mx_remote-5.5.1 → mx_remote-5.7.0}/mx_remote/proto/FrameHello.py

@@ -19,7 +19,20 @@ class FrameHello(FrameBase):
     '''Hello frame, sent by devices to advertise themselves on the network.'''
     @staticmethod
     def construct(mxr:DeviceRegistry) -> FrameBase|None:
-        '''Build a hello frame for transmission to advertise this client.'''
+        '''Build a hello frame for transmission to advertise this client.
+
+        Never append a field to this payload. Receivers read a payload length as
+        a minimum everywhere except the hello, which they check exactly, so a
+        hello that grew is discarded rather than read up to the part they know.
+        That costs more than the field: this is how the client stops being
+        unknown, and a receiver that drops it never registers the sender and
+        ignores everything that follows as coming from a stranger.
+
+        It holds however many receivers are later fixed to accept a longer
+        hello, because the ones already deployed are the ones deciding whether
+        this client is seen at all. Nothing on the receive side needs the rule -
+        FrameHello reads its fields by offset with no length gate, so a peer may
+        grow its own.'''
         payload = [ (MXR_PROTOCOL_VERSION & 0xFF), ((MXR_PROTOCOL_VERSION >> 8) & 0xFF) ]
         payload = append_payload_str(payload=payload, value=mxr.name, sz=16)
         payload = append_payload_str(payload=payload, value="P9SN00000000", sz=16)