mx-remote 5.9.0__tar.gz → 5.10.0__tar.gz

{mx_remote-5.9.0 → mx_remote-5.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mx_remote
-Version: 5.9.0
+Version: 5.10.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.9.0 → mx_remote-5.10.0}/docs/api.md

@@ -57,3 +57,20 @@ The key and action codes a bay reports, and the target a key was aimed at.
 
 .. autodata:: mx_remote.proto.Constants.MXR_PROTOCOL_VERSION
 ```
+
+## V2IP device settings
+
+The settings a V2IP device reports and a controller writes, each behind its own
+bit, and the range of the infrared profiles.
+
+```{eval-rst}
+.. autoclass:: mx_remote.proto.Constants.V2IPDeviceSetting
+   :members:
+   :undoc-members:
+
+.. autodata:: mx_remote.proto.Constants.V2IP_DEVICE_SETTING_SWITCHES
+
+.. autodata:: mx_remote.proto.Constants.V2IP_IR_PROFILE_NOT_SET
+
+.. autodata:: mx_remote.proto.Constants.V2IP_IR_PROFILE_MAX
+```

{mx_remote-5.9.0 → mx_remote-5.10.0}/docs/oneip.md

@@ -141,16 +141,15 @@ expect `device.v2ip_sink` to read empty for a moment afterwards - see
 
 `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
+of a device configuration with no validity marker of its own, so a sink with
+nothing to say sends zeros and the library 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
+and rebroadcasts the block, 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.
@@ -159,6 +158,40 @@ 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.
 
+Only the device's own report sets the block. A controller writing another
+device's configuration sends it zeroed, and the library ignores that copy.
+
+## Device settings
+
+A V2IP device reports its settings in its configuration: decoder auto-disable,
+HDMI off without signal, IR modulation, the status and network LEDs, quiet fan,
+CEC combo keys, and the infrared profiles. Each sits behind its own bit, so a
+device reports only the settings it has, and a write changes one without
+restating the rest.
+
+```python
+from mx_remote import V2IPDeviceSetting
+
+settings = device.v2ip_settings             # None until the device has reported
+print(settings.get(V2IPDeviceSetting.FAN_QUIET))   # None: the device lacks it
+print(settings.ir_profile, settings.ir_profile_sink)
+
+await device.set_v2ip_setting(V2IPDeviceSetting.STATUS_LED, False)
+await device.set_v2ip_ir_profile(2)
+await device.set_v2ip_sink_ir_profile(mx_remote.V2IP_IR_PROFILE_NOT_SET)  # follow the global port
+```
+
+A write returns False, without sending anything, for whatever the device would
+ignore in silence: a setting it has not reported, a profile out of range, or a
+device that has reported no settings at all. So a True is never a change that
+does not happen, though nothing acknowledges it either: the device answers by
+reporting its settings, and until then `v2ip_settings` reads back what was
+written.
+
+A write from another controller is cached only as far as the device takes it.
+The list of stored infrared profiles is the device's own and is never taken
+from a write.
+
 ## Mesh and firmware
 
 ```python

{mx_remote-5.9.0 → mx_remote-5.10.0}/mx_remote/Interface.py

@@ -1757,8 +1757,8 @@ class DeviceV2IPSink:
 
     **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
+    a device configuration with no validity marker of its own, so a sink with
+    nothing to say sends zeros and they are stored. 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
@@ -1766,8 +1766,7 @@ class DeviceV2IPSink:
     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
+    the device rebuild and rebroadcast this block, 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
@@ -1776,6 +1775,9 @@ class DeviceV2IPSink:
     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.
+
+    Only the device's own report sets this. A controller writing another
+    device's configuration sends the block zeroed, and that frame is ignored.
     """
     def __init__(self, addresses:V2IPStreamSources|None, audio_fmt:V2IPAudioFormat|None) -> None:
         self._addresses = addresses
@@ -1792,6 +1794,122 @@ class DeviceV2IPSink:
     def __str__(self) -> str:
         return f"addresses=[{self._addresses}] audio_fmt={self._audio_fmt}"
 
+class V2IPDeviceSettings:
+    """
+    The device settings of a V2IP unit, as it reports them and as its controller
+    changes them.
+
+    Each setting is carried only behind its bit in ``valid``, so a frame changes
+    one setting without restating the others, and a device reports only the
+    settings it has. Read a setting through ``get()`` and the profile
+    properties, which answer None for one the device has not reported.
+    """
+    def __init__(self, valid:V2IPDeviceSetting=V2IPDeviceSetting(0),
+                 flags:V2IPDeviceSetting=V2IPDeviceSetting(0), ir_profiles:int=0,
+                 ir_profile:int=0, ir_profile_sink:int=0) -> None:
+        self._valid = V2IPDeviceSetting(valid)
+        self._flags = V2IPDeviceSetting(flags)
+        self._ir_profiles = ir_profiles
+        self._ir_profile = ir_profile
+        self._ir_profile_sink = ir_profile_sink
+
+    @property
+    def valid(self) -> V2IPDeviceSetting:
+        """The settings reported so far."""
+        return self._valid
+
+    @property
+    def flags(self) -> V2IPDeviceSetting:
+        """The values of the on/off settings among ``valid``."""
+        return self._flags
+
+    def get(self, setting:V2IPDeviceSetting) -> bool|None:
+        """Whether an on/off setting is on, None while the device has not reported it."""
+        if ((self._valid & setting) != setting):
+            return None
+        return ((self._flags & setting) == setting)
+
+    @property
+    def ir_profile(self) -> int|None:
+        """The global infrared port's profile, None while it is not reported."""
+        if (V2IPDeviceSetting.IR_PROFILE not in self._valid):
+            return None
+        return self._ir_profile
+
+    @property
+    def ir_profile_sink(self) -> int|None:
+        """The output infrared port's profile, None while it is not reported.
+        V2IP_IR_PROFILE_NOT_SET means the port follows the global one."""
+        if (V2IPDeviceSetting.IR_PROFILE_SINK not in self._valid):
+            return None
+        return self._ir_profile_sink
+
+    @property
+    def stored_ir_profiles(self) -> int|None:
+        """The infrared profiles stored on the device, bit n for profile n, None
+        while it is not reported."""
+        if (V2IPDeviceSetting.IR_PROFILES not in self._valid):
+            return None
+        return self._ir_profiles
+
+    def merge(self, previous:'V2IPDeviceSettings|None') -> 'V2IPDeviceSettings':
+        """
+        Fold this received block onto the cached one.
+
+        Each bit in this block's ``valid`` replaces its own setting and leaves
+        the others alone, so a write about one setting does not clear what was
+        known about the rest.
+        """
+        if (previous is None):
+            previous = V2IPDeviceSettings()
+        valid = self._valid
+        return V2IPDeviceSettings(
+            valid=(previous._valid | valid),
+            flags=((previous._flags & ~valid) | (self._flags & valid)),
+            ir_profiles=(self._ir_profiles if (V2IPDeviceSetting.IR_PROFILES in valid)
+                         else previous._ir_profiles),
+            ir_profile=(self._ir_profile if (V2IPDeviceSetting.IR_PROFILE in valid)
+                        else previous._ir_profile),
+            ir_profile_sink=(self._ir_profile_sink if (V2IPDeviceSetting.IR_PROFILE_SINK in valid)
+                             else previous._ir_profile_sink))
+
+    def as_applied_to(self, reported:V2IPDeviceSetting) -> 'V2IPDeviceSettings':
+        """
+        This block limited to what a device takes from a write about it.
+
+        A device applies a setting only if it has it, a profile only within its
+        range, and never the list of stored profiles, which only it knows.
+        """
+        valid = (self._valid & reported) & ~V2IPDeviceSetting.IR_PROFILES
+        if not (0 <= self._ir_profile < V2IP_IR_PROFILE_MAX):
+            valid &= ~V2IPDeviceSetting.IR_PROFILE
+        if not (V2IP_IR_PROFILE_NOT_SET <= self._ir_profile_sink < V2IP_IR_PROFILE_MAX):
+            valid &= ~V2IPDeviceSetting.IR_PROFILE_SINK
+        return V2IPDeviceSettings(valid=valid, flags=self._flags, ir_profiles=self._ir_profiles,
+                                  ir_profile=self._ir_profile, ir_profile_sink=self._ir_profile_sink)
+
+    def __eq__(self, other:Any) -> bool:
+        if not isinstance(other, V2IPDeviceSettings):
+            return NotImplemented
+        return ((self._valid, self._flags, self._ir_profiles, self._ir_profile, self._ir_profile_sink)
+                == (other._valid, other._flags, other._ir_profiles, other._ir_profile, other._ir_profile_sink))
+
+    def __ne__(self, other:Any) -> bool:
+        result = self.__eq__(other)
+        return result if (result is NotImplemented) else (not result)
+
+    def __str__(self) -> str:
+        parts = [f"{setting.name}={'on' if self.get(setting) else 'off'}"
+                 for setting in V2IPDeviceSetting
+                 if (setting in V2IP_DEVICE_SETTING_SWITCHES) and (self.get(setting) is not None)]
+        if (self.ir_profile is not None):
+            parts.append(f"ir_profile={self.ir_profile}")
+        if (self.ir_profile_sink is not None):
+            parts.append(f"ir_profile_sink={self.ir_profile_sink}")
+        if (self.stored_ir_profiles is not None):
+            parts.append(f"ir_profiles={self.stored_ir_profiles:#x}")
+        return " ".join(parts)
+
     def __repr__(self) -> str:
         return str(self)
 
@@ -2101,6 +2219,15 @@ class DeviceBase(ABC):
     def v2ip_sink(self) -> DeviceV2IPSink|None:
         '''V2IP sink-side multicast subscriptions and resolved audio format (None until first announced)'''
 
+    @property
+    @abstractmethod
+    def v2ip_settings(self) -> V2IPDeviceSettings|None:
+        '''The V2IP device settings, None until the device has reported any.
+
+        A device reports only the settings it has, so one missing from valid
+        once the rest have arrived is one the device does not have.
+        '''
+
     @property
     @abstractmethod
     def v2ip_source_local(self) -> V2IPStreamSources|None:
@@ -2275,8 +2402,8 @@ class DeviceBase(ABC):
         '''merge one frame of this device's V2IP source list into the cached list'''
 
     @abstractmethod
-    def note_link_record(self, port:int) -> None:
-        '''internal callback: the bay on this port reported its link record'''
+    def note_link_config(self) -> None:
+        '''internal callback: a page of the link configuration was received'''
 
     @abstractmethod
     def note_bay_config(self) -> None:
@@ -2322,6 +2449,18 @@ class DeviceBase(ABC):
     async def clear_v2ip_output_mode(self) -> bool:
         '''clear the output format this sink is configured to scale to'''
 
+    @abstractmethod
+    async def set_v2ip_setting(self, setting:V2IPDeviceSetting, enabled:bool) -> bool:
+        '''switch on/off V2IP device settings, all to the same value'''
+
+    @abstractmethod
+    async def set_v2ip_ir_profile(self, profile:int) -> bool:
+        '''set the infrared profile of the device's global infrared port'''
+
+    @abstractmethod
+    async def set_v2ip_sink_ir_profile(self, profile:int) -> bool:
+        '''set the infrared profile of the device's output infrared port'''
+
     @abstractmethod
     async def get_log(self) -> str|None:
         '''read the log from the device and return it as string'''

{mx_remote-5.9.0 → mx_remote-5.10.0}/mx_remote/Interface.pyi

@@ -656,6 +656,24 @@ class DeviceV2IPSink:
     @property
     def audio_fmt(self) -> V2IPAudioFormat | None: ...
 
+class V2IPDeviceSettings:
+    def __init__(self, valid: V2IPDeviceSetting = ..., flags: V2IPDeviceSetting = ..., ir_profiles: int = 0, ir_profile: int = 0, ir_profile_sink: int = 0) -> None: ...
+    @property
+    def valid(self) -> V2IPDeviceSetting: ...
+    @property
+    def flags(self) -> V2IPDeviceSetting: ...
+    def get(self, setting: V2IPDeviceSetting) -> bool | None: ...
+    @property
+    def ir_profile(self) -> int | None: ...
+    @property
+    def ir_profile_sink(self) -> int | None: ...
+    @property
+    def stored_ir_profiles(self) -> int | None: ...
+    def merge(self, previous: V2IPDeviceSettings | None) -> V2IPDeviceSettings: ...
+    def as_applied_to(self, reported: V2IPDeviceSetting) -> V2IPDeviceSettings: ...
+    def __eq__(self, other: Any) -> bool: ...
+    def __ne__(self, other: Any) -> bool: ...
+
 class UtpLinkErrorStatus(ABC):
     @property
     @abstractmethod
@@ -838,6 +856,9 @@ class DeviceBase(ABC):
     def v2ip_sink(self) -> DeviceV2IPSink | None: ...
     @property
     @abstractmethod
+    def v2ip_settings(self) -> V2IPDeviceSettings | None: ...
+    @property
+    @abstractmethod
     def v2ip_source_local(self) -> V2IPStreamSources | None: ...
     @property
     @abstractmethod
@@ -916,7 +937,7 @@ class DeviceBase(ABC):
     @abstractmethod
     def merge_v2ip_sources(self, first: int, total: int, page: V2IPStreamSourcesList) -> None: ...
     @abstractmethod
-    def note_link_record(self, port: int) -> None: ...
+    def note_link_config(self) -> None: ...
     @abstractmethod
     def note_bay_config(self) -> None: ...
     @abstractmethod
@@ -940,6 +961,12 @@ class DeviceBase(ABC):
     @abstractmethod
     async def clear_v2ip_output_mode(self) -> bool: ...
     @abstractmethod
+    async def set_v2ip_setting(self, setting: V2IPDeviceSetting, enabled: bool) -> bool: ...
+    @abstractmethod
+    async def set_v2ip_ir_profile(self, profile: int) -> bool: ...
+    @abstractmethod
+    async def set_v2ip_sink_ir_profile(self, profile: int) -> bool: ...
+    @abstractmethod
     async def get_log(self) -> str | None: ...
     @abstractmethod
     def on_mxr_update(self, data: object) -> None: ...

{mx_remote-5.9.0 → mx_remote-5.10.0}/mx_remote/const.py

@@ -14,7 +14,7 @@ Default communication modes:
 """
 import os
 
-VERSION = '5.9.0'
+VERSION = '5.10.0'
 __version__ = VERSION
 
 MX_BCAST_UDP_PORT = 8811
@@ -37,6 +37,14 @@ re-drawn after every hello that is sent, so devices announcing on the same mesh
 not converge into synchronised bursts.
 """
 
+MXR_CONFIG_TIMEOUT = 15
+"""How long a device is given to finish describing itself, in seconds.
+
+Past this a device is reported as fully described without its link
+configuration, and keeps being asked for the rest. It never stands in for the
+bay configuration - see ``Device.has_bays``.
+"""
+
 V2IP_UDP_PORT_VIDEO = 50020
 """Default destination UDP port for a V2IP video stream (firmware ``V2IP_UDP_PORT_VIDEO``)."""
 

{mx_remote-5.9.0 → mx_remote-5.10.0}/mx_remote/const.pyi

@@ -7,6 +7,7 @@ MX_MCAST_UDP_IP: str
 MX_MCAST_UDP_PORT: int
 MXR_HELLO_INTERVAL_MIN: float
 MXR_HELLO_INTERVAL_RAND: float
+MXR_CONFIG_TIMEOUT: int
 V2IP_UDP_PORT_VIDEO: int
 V2IP_UDP_PORT_ANC: int
 V2IP_UDP_PORT_AUDIO: int

{mx_remote-5.9.0 → mx_remote-5.10.0}/mx_remote/proto/Constants.py

@@ -10,7 +10,7 @@
 from enum import IntEnum, IntFlag
 from typing import TypeVar
 
-MXR_PROTOCOL_VERSION = 0x29
+MXR_PROTOCOL_VERSION = 0x2A
 """Highest mx_remote protocol version this library understands.
 
 Mirrors the firmware's own protocol version. Bump
@@ -21,7 +21,14 @@ 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."""
+0x29 is what a MatrixOS 10.12.46 unit stamps on V2IP_STATS.
+
+0x2A is also what MatrixOS reads a hello by: a device on 0x2A or later is given
+60s to hello again rather than 15s, and a unit only slows its own hello to one
+every 20-30s once every device it knows is on 0x2A."""
+
+MXR_PROTOCOL_VERSION_SLOW_HELLO = 0x2A
+"""First protocol version whose devices may hello only every 20-30s."""
 
 MXR_OPCODE_VERSIONS: dict[int, int] = {
     0x00: 0x01,  # SYS_HELLO
@@ -258,6 +265,50 @@ class V2IPFpgaFeature(IntFlag):
 	SINK_STREAM_INFO   = (1 << 5)
 	'''Reports information about the stream its sink receives.'''
 
+class V2IPDeviceSetting(IntFlag):
+	'''The device settings a V2IP configuration can carry, each on its own bit.
+
+	The same bits serve as the settings a frame carries and as the values of the
+	on/off ones among them. The last three carry a value elsewhere in the block
+	and have no on/off value of their own.
+
+	A device reports every setting it has, so one it never reports is one it
+	does not have.'''
+	SINK_CHECK_POWER   = (1 << 0)
+	'''Disables the decoder while the display is off.'''
+	SINK_OFF_NO_SIGNAL = (1 << 1)
+	'''Disables the HDMI output while there is no signal.'''
+	IR_TX_MODULATED    = (1 << 2)
+	'''Sends infrared modulated.'''
+	STATUS_LED         = (1 << 3)
+	'''Lights the status LED.'''
+	NETWORK_LED        = (1 << 4)
+	'''Lights the network port LEDs.'''
+	FAN_QUIET          = (1 << 5)
+	'''Runs the fan in quiet mode.'''
+	CEC_COMBO_KEYS     = (1 << 6)
+	'''Accepts CEC combo keys.'''
+	CEC_COMBO_INPUT    = (1 << 7)
+	'''Accepts CEC combo keys for the device's own input.'''
+	IR_PROFILE         = (1 << 8)
+	'''The infrared profile of the device's global infrared port.'''
+	IR_PROFILE_SINK    = (1 << 9)
+	'''The infrared profile of the output's infrared port.'''
+	IR_PROFILES        = (1 << 10)
+	'''The infrared profiles stored on the device. Reported by the device
+	itself and never written.'''
+
+V2IP_DEVICE_SETTING_SWITCHES = V2IPDeviceSetting(0xFF)
+"""The settings that are on or off, as opposed to carrying a value."""
+
+V2IP_IR_PROFILE_NOT_SET = -1
+"""The infrared profile an output's port reports when it follows the device's
+global one."""
+
+V2IP_IR_PROFILE_MAX = 18
+"""One past the highest infrared profile: the default profile is 0, the Atlona
+profile 1, and user-defined profiles 1 to 16 are 2 to 17."""
+
 BAY_FEATURE_DOLBY_IN_POS = 24
 
 class BayFeaturesMask(IntFlag):

{mx_remote-5.9.0 → mx_remote-5.10.0}/mx_remote/proto/Constants.pyi

@@ -2,6 +2,7 @@ from _typeshed import Incomplete
 from enum import IntEnum, IntFlag
 
 MXR_PROTOCOL_VERSION: int
+MXR_PROTOCOL_VERSION_SLOW_HELLO: int
 MXR_OPCODE_VERSIONS: dict[int, int]
 MXR_CFG_SIGNAL_STATUS_LEN: int
 MXR_DEVICE_NAME_LEN: int
@@ -68,6 +69,22 @@ class V2IPFpgaFeature(IntFlag):
     SINK_STATE: Incomplete
     SINK_STREAM_INFO: Incomplete
 
+class V2IPDeviceSetting(IntFlag):
+    SINK_CHECK_POWER: Incomplete
+    SINK_OFF_NO_SIGNAL: Incomplete
+    IR_TX_MODULATED: Incomplete
+    STATUS_LED: Incomplete
+    NETWORK_LED: Incomplete
+    FAN_QUIET: Incomplete
+    CEC_COMBO_KEYS: Incomplete
+    CEC_COMBO_INPUT: Incomplete
+    IR_PROFILE: Incomplete
+    IR_PROFILE_SINK: Incomplete
+    IR_PROFILES: Incomplete
+
+V2IP_DEVICE_SETTING_SWITCHES: Incomplete
+V2IP_IR_PROFILE_NOT_SET: int
+V2IP_IR_PROFILE_MAX: int
 BAY_FEATURE_DOLBY_IN_POS: int
 
 class BayFeaturesMask(IntFlag):

{mx_remote-5.9.0 → mx_remote-5.10.0}/mx_remote/proto/FrameLinks.py

@@ -44,11 +44,7 @@ class FrameLinks(FrameBase):
             return
         for link in self.links:
             link.process()
-            # Only a record that landed on a known bay counts. One naming a bay
-            # this client has not seen is dropped rather than held, which is
-            # what a device does with the same frame, and the device re-sends.
-            if (link.remote_bay is not None):
-                dev.note_link_record(link.remote_port)
+        dev.note_link_config()
 
     def __str__(self) -> str:
         return f"{self.remote_device} links config page: {len(self.links)} links"

{mx_remote-5.9.0 → mx_remote-5.10.0}/mx_remote/proto/FrameV2IPDeviceConfiguration.py

@@ -12,8 +12,10 @@ from .FrameBase import FrameBase
 from .FrameHeader import FrameHeader
 from ..Uid import MxrDeviceUid
 from ..Interface import (DeviceBase, DeviceRegistry, DeviceV2IPDetails, DeviceV2IPScalingSettings,
-                         DeviceV2IPSink, V2IPAudioFormat, V2IPDscpConfig, V2IPStreamSource)
-from .Constants import (V2IPFpgaFeature, MXR_SCALING_FLAG_AUTO_SCALING, MXR_SCALING_FLAG_MODE_VALID,
+                         DeviceV2IPSink, V2IPAudioFormat, V2IPDeviceSettings, V2IPDscpConfig,
+                         V2IPStreamSource)
+from .Constants import (V2IPDeviceSetting, V2IPFpgaFeature, MXR_SCALING_FLAG_AUTO_SCALING,
+                        MXR_SCALING_FLAG_MODE_VALID,
                         MXR_SCALING_FLAG_OPTIONS_VALID, MXR_SCALING_FLAG_OPTIONS2_VALID,
                         MXR_SCALING_OPTIONS2_SETTINGS, MxrSignalType, v2ip_dscp_value,
                         v2ip_rate_valid)
@@ -30,6 +32,8 @@ from .V2IPConfig import V2IPStreamSourceImpl, parse_v2ip_av_source
 #    88..112  v2ip_av_source sink, zero when no route is active
 #   112..120  v2ip_audio_format sink_audio_fmt
 #   120..128  u64 video processor feature mask
+#   128..144  device settings: u32 valid, u32 flags, u32 stored ir profiles,
+#             s8 ir_profile, s8 ir_profile_sink, 2 reserved
 #
 # Each of those blocks was appended behind what came before it, leaving every
 # offset ahead of it where it was, so the length is what says whether one is
@@ -52,7 +56,8 @@ from .V2IPConfig import V2IPStreamSourceImpl, parse_v2ip_av_source
 # DeviceV2IPDetails.merge() carries the unmarked fields forward. Replacing the
 # cache wholesale reports a peer's addresses as 0.0.0.0 the moment a controller
 # writes anything else. The sink trailer is the exception: present or absent by
-# length, with no marker.
+# length, with no marker, and taken only from a device describing itself.
+# The settings block marks each setting with its own bit in valid.
 #
 # Trust the scaling block only from a peer whose hello carries
 # MXR_FEATURE_CONFIG_INITIALISED. Without it the sender may have built those
@@ -80,6 +85,9 @@ _SINK_OFFSET        = _BASE_SIZE
 _SINK_AUDIO_OFFSET  = _BASE_SIZE + 24
 _CODEC_OFFSET       = _WITH_OPTIONS_SIZE
 _CODEC_SIZE         = 8
+_SETTINGS_OFFSET    = _CODEC_OFFSET + _CODEC_SIZE
+_SETTINGS_SIZE      = 16
+_WITH_SETTINGS_SIZE = _SETTINGS_OFFSET + _SETTINGS_SIZE
 
 class V2IPDeviceOptions:
     '''Parsed V2IP device options (TX rate and per-stream DSCP marking).'''
@@ -236,6 +244,46 @@ class FrameV2IPDeviceConfiguration(FrameBase):
         payload += bytes(_BASE_SIZE - len(payload))
         return FrameBase.construct_base(target=target, mxr=mxr, opcode=_OPCODE, payload=bytes(payload))
 
+    @staticmethod
+    def construct_settings(mxr:DeviceRegistry, target:Any, target_uid:MxrDeviceUid,
+                           settings:V2IPDeviceSettings) -> FrameBase|None:
+        '''Build the 0x3C write that changes a device's settings and nothing else.
+
+        144 bytes: the configuration as construct_scaling() lays it out but with
+        no scaling validity bit, then the options trailer - the sink block at
+        88..120, the processor's feature word at 120..128 and the settings at
+        128..144. The settings are the last block, so a frame that carries them
+        carries the two before them too.
+
+        **Both of those go out zeroed.** A device leaves the feature word zero on
+        a frame about another device, and a receiver takes the sink block only
+        from a device describing itself - except on a receiver that predates the
+        settings block, which copies it into its record of the target until the
+        target next reports. That is the frame a controlling device sends for
+        the same change.
+
+        Only the settings named in settings.valid are carried; the device keeps
+        the rest.
+        '''
+        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)
+        # No dscp, no audio return, a scaling block without a validity bit and a
+        # tiling window whose zero uid says none is carried; then the zeroed
+        # sink block and feature word.
+        payload += bytes(_SETTINGS_OFFSET - len(payload))
+        payload += int(settings.valid).to_bytes(4, 'little')
+        payload += int(settings.flags).to_bytes(4, 'little')
+        # A value not named in valid is not read, so it goes out as zero.
+        payload += (settings.stored_ir_profiles or 0).to_bytes(4, 'little')
+        payload += (settings.ir_profile or 0).to_bytes(1, 'little', signed=True)
+        payload += (settings.ir_profile_sink or 0).to_bytes(1, 'little', signed=True)
+        payload += bytes(_WITH_SETTINGS_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)
@@ -312,14 +360,47 @@ class FrameV2IPDeviceConfiguration(FrameBase):
     @cached_property
     def sink(self) -> DeviceV2IPSink|None:
         '''Sink-side state a longer frame appends to the configuration; None when
-        the frame stops in front of it.'''
+        the frame stops in front of it.
+
+        Read only from a frame a device sent about itself. A controller writing
+        another device's configuration sends the block zeroed, because it has
+        nothing to say about that sink's subscription, and caching those zeros
+        would clear the route on every unrelated write.
+        '''
         if (self.payload is None) or (len(self.payload) < _WITH_OPTIONS_SIZE):
             return None
+        if not self.target_self:
+            return None
         return DeviceV2IPSink(
             addresses=parse_v2ip_av_source(self.payload, _SINK_OFFSET),
             audio_fmt=V2IPAudioFormat.from_bytes(self.payload[_SINK_AUDIO_OFFSET:_SINK_AUDIO_OFFSET + 8]),
         )
 
+    @cached_property
+    def settings(self) -> V2IPDeviceSettings|None:
+        '''The device settings block, as the subject will hold it; None when the
+        frame stops in front of it or nothing would act on it.
+
+        A device reports every setting it has. A controller sends only the ones
+        it changes, and the device applies only those it has, so a write is
+        limited here to what the device will take from it and no further.
+        '''
+        if (self.payload is None) or (len(self.payload) < _WITH_SETTINGS_SIZE):
+            return None
+        if ((dev := self.subject_device) is None):
+            return None
+        block = self.payload[_SETTINGS_OFFSET:_WITH_SETTINGS_SIZE]
+        frame = V2IPDeviceSettings(
+            valid=V2IPDeviceSetting(int.from_bytes(block[0:4], 'little')),
+            flags=V2IPDeviceSetting(int.from_bytes(block[4:8], 'little')),
+            ir_profiles=int.from_bytes(block[8:12], 'little'),
+            ir_profile=int.from_bytes(block[12:13], 'little', signed=True),
+            ir_profile_sink=int.from_bytes(block[13:14], 'little', signed=True))
+        if self.target_self:
+            return frame
+        reported = dev.v2ip_settings
+        return frame.as_applied_to(reported.valid if (reported is not None) else V2IPDeviceSetting(0))
+
     def process(self) -> None:
         '''Update the cache of the device this configuration names, not of its sender.'''
         if ((dev := self.subject_device) is None):
@@ -329,8 +410,11 @@ class FrameV2IPDeviceConfiguration(FrameBase):
             dev.on_mxr_update(sink)
         if ((features := self.video_processor_features) is not None):
             dev.on_mxr_update(features)
+        if ((settings := self.settings) is not None):
+            dev.on_mxr_update(settings)
 
     def __str__(self) -> str:
         sink_str = f" sink=[{self.sink}]" if (self.sink is not None) else ""
         fpga_str = f" fpga={self.video_processor_features}" if (self.video_processor_features is not None) else ""
-        return f"V2IP device configuration self={self.target_self} {self.video} {self.audio} {self.anc} {self.arc} options={self.options}{sink_str}{fpga_str}"
+        settings_str = f" settings=[{self.settings}]" if (self.settings is not None) else ""
+        return f"V2IP device configuration self={self.target_self} {self.video} {self.audio} {self.anc} {self.arc} options={self.options}{sink_str}{fpga_str}{settings_str}"