mx-remote 8.1.0__tar.gz → 9.0.0__tar.gz

{mx_remote-8.1.0 → mx_remote-9.0.0}/PKG-INFO

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

@@ -85,6 +85,23 @@ place, backgrounds and logo images.
 .. autodata:: mx_remote.proto.Constants.OSD_SYNC_PERCENT_MAX
 ```
 
+## Overlay messages
+
+The message on a unit's output, which the overlay sync opcode carries too.
+
+```{eval-rst}
+.. autoclass:: mx_remote.OsdMessage
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OsdMessageFlag
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.OsdMessagePriority
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.OSD_MESSAGE_TEXT_MAX
+```
+
 ## Device identity
 
 ```{eval-rst}
@@ -180,6 +197,8 @@ state only the device reports.
 
 .. autodata:: mx_remote.proto.Constants.ONEIP_STREAM_TTL_DEFAULT
 
+.. autodata:: mx_remote.proto.Constants.ONEIP_SINK_ROTATION_MAX
+
 .. autodata:: mx_remote.proto.Constants.ONEIP_PTP_DOMAIN_MAX
 ```
 

{mx_remote-8.1.0 → mx_remote-9.0.0}/docs/oneip.md

@@ -288,10 +288,23 @@ same block, behind `SAP_EXPIRE` and `SAP_INTERVAL`, and are set the same way;
 `SAP_LISTEN` and `SAP_ANNOUNCE` are switches like the other on/off settings.
 A device with an encoder reports its streams' TTL there too, behind
 `STREAM_TTL`; a TTL of 0 is refused, as a device changes nothing for one.
+A device with an HDMI output reports the angle its output is turned by,
+clockwise, behind `SINK_ROTATION`, with the step its video processor turns by.
+It takes 0 or a multiple of that step up to `ONEIP_SINK_ROTATION_MAX`, so any
+other angle is refused before it is sent, and the step is never written.
+`set_all_oneip_device_settings` can only check the range; each device judges
+the step.
+
+```python
+m = settings.ptp_messages
+print(m.sink_rotation, m.sink_rotation_step)   # e.g. 0 and 90
+await device.set_oneip_ptp_messages(OneIPDeviceSetting.SINK_ROTATION,
+                                    OneIPPtpMessages(sink_rotation=180))
+```
 
 Only the values behind the bits named are sent. A DSCP above `ONEIP_DSCP_MAX` is
 refused, and not cached from another controller's write. A write carrying one of
-these runs on to 224 bytes, or 232 with the TTL; every other write keeps the 176
+these runs on to 224 bytes, or 232 with the TTL or the rotation; every other write keeps the 176
 every device knows.
 
 What the device's clock is actually doing is its PTP state, which only the
@@ -412,13 +425,34 @@ await mx.clear_osd_sync()          # stop answering for it
 Each unit asks for the settings it lacks and takes only those, so this client
 holds the content and answers until it is replaced or cleared, announcing
 itself meanwhile as the mesh's overlay sync manager: a unit waking from power
-save then takes this content rather than the controller's. The controller
-still answers a unit that asks for settings without naming whose sync they are
-from, as an older overlay module does, with its own sync, which replaces this
-client's on that unit. Logo images are
+save then takes this content rather than the controller's. Logo images are
 served over HTTP from this client, on `logo_port` or a free port. Content a unit
 would refuse is refused before anything is sent; see `send_osd_sync`.
 
+### Overlay messages
+
+A unit shows a message on its output, over the picture, until it restarts. The
+text is markup of at most `OSD_MESSAGE_TEXT_MAX` bytes with no control
+character, shown with a logo: 0 the built-in one, -1 none, 1 to 5 a slot. Its
+priority places it against the unit's own messages, such as Locate Device.
+
+```python
+from mx_remote.proto.Constants import OsdMessagePriority
+
+await sink.show_osd_message('Back at <b>3</b>', logo=-1, priority=OsdMessagePriority.TOP)
+await sink.request_osd_message()   # the unit answers with what it shows
+await sink.clear_osd_message()
+
+print(sink.osd_message)   # None until the unit has answered
+```
+
+A unit takes a message only from management, which this client announces
+itself as, and answers every write and request with the message it then has;
+`on_osd_message_changed` reports a change. The answer carries
+`OsdMessageFlag.REFUSED` when the unit did not take the write, as when its
+video processor has no message layer. A text, logo or priority a unit would
+refuse is refused before it is sent, as is a device that is not a OneIP output.
+
 ### Stream encryption
 
 A source unit from protocol 0x30 encrypts its video, audio and ancillary

{mx_remote-8.1.0 → mx_remote-9.0.0}/mx_remote/Interface.py

@@ -6,7 +6,7 @@
 ######################################################
 
 from abc import ABC, abstractmethod
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from datetime import datetime, timezone
 from enum import IntEnum
 import time
@@ -2215,8 +2215,8 @@ def _wire_enum(cls:Any, value:int) -> Any:
 @dataclass(frozen=True)
 class OneIPPtpMessages:
     """
-    How a OneIP device paces its PTP messages, its SAP timings and its streams'
-    TTL, which a frame carries in the same block. Each value is behind its own bit of
+    How a OneIP device paces its PTP messages, its SAP timings, its streams'
+    TTL and its output's rotation, which a frame carries in the same block. Each value is behind its own bit of
     OneIPDeviceSettings.valid, one of ONEIP_DEVICE_SETTINGS_BLOCK.
 
     Intervals are base-2 logarithms of seconds, so -3 is 125 ms and 1 is 2 s.
@@ -2241,6 +2241,19 @@ class OneIPPtpMessages:
     """The TTL of the device's streams, 1 to 255, behind STREAM_TTL. A device
     whose video processor cannot change it keeps the setting and sends
     ONEIP_STREAM_TTL_DEFAULT."""
+    sink_rotation: int = 0
+    """The degrees the device's HDMI output is turned by, clockwise, at most
+    ONEIP_SINK_ROTATION_MAX, behind SINK_ROTATION."""
+    sink_rotation_step: int = 0
+    """The step the output turns by: the device takes only an angle that is a
+    multiple of it, and 0 alone when it is 0. Only the device reports it,
+    behind the same bit."""
+
+    def takes_sink_rotation(self, degrees:int) -> bool:
+        """Whether a device reporting this step takes degrees as its output's
+        rotation."""
+        return (degrees == 0) or ((0 < degrees <= ONEIP_SINK_ROTATION_MAX) and (self.sink_rotation_step != 0)
+                                  and (degrees % self.sink_rotation_step == 0))
 
     def merge(self, other:'OneIPPtpMessages', which:OneIPDeviceSetting) -> 'OneIPPtpMessages':
         """The values behind the bits of which copied from other, the rest kept."""
@@ -2253,7 +2266,9 @@ class OneIPPtpMessages:
             dscp=(other if (S.PTP_DSCP in which) else self).dscp,
             sap_expire_min=(other if (S.SAP_EXPIRE in which) else self).sap_expire_min,
             sap_interval_s=(other if (S.SAP_INTERVAL in which) else self).sap_interval_s,
-            stream_ttl=(other if (S.STREAM_TTL in which) else self).stream_ttl)
+            stream_ttl=(other if (S.STREAM_TTL in which) else self).stream_ttl,
+            sink_rotation=(other if (S.SINK_ROTATION in which) else self).sink_rotation,
+            sink_rotation_step=(other if (S.SINK_ROTATION in which) else self).sink_rotation_step)
 
     def describe(self, valid:OneIPDeviceSetting) -> list[str]:
         """The values behind the bits of valid, one "name=value" each."""
@@ -2266,7 +2281,8 @@ class OneIPPtpMessages:
                     (S.PTP_DSCP, 'ptp_dscp', self.dscp),
                     (S.SAP_EXPIRE, 'sap_expire_min', self.sap_expire_min),
                     (S.SAP_INTERVAL, 'sap_interval_s', self.sap_interval_s),
-                    (S.STREAM_TTL, 'stream_ttl', self.stream_ttl))
+                    (S.STREAM_TTL, 'stream_ttl', self.stream_ttl),
+                    (S.SINK_ROTATION, 'sink_rotation', self.sink_rotation))
                 if (bit in valid)]
 
 @dataclass(frozen=True)
@@ -2317,8 +2333,7 @@ class OsdSyncRequest:
     missing: bytes
     """The settings it lacks, bit i standing for setting i, 16 bytes."""
     source: MxrDeviceUid
-    """Who sent the sync it asks about. Empty when it asks for a new sync, and
-    from a unit whose module does not name the source."""
+    """Who sent the sync it asks about. Empty when it asks for a new sync."""
 
     def is_missing(self, index:int) -> bool:
         """Whether the unit lacks setting index."""
@@ -2394,6 +2409,28 @@ class OsdSyncReport:
     reason: str
     """Why it failed or refused any."""
 
+@dataclass(frozen=True)
+class OsdMessage:
+    """
+    The message on a unit's output, as the unit last reported it. The unit
+    holds it until it restarts.
+    """
+    flags: OsdMessageFlag
+    """Whether a message is set and shown, whether the unit can show one, and
+    whether it refused the write it answers. Without SET the other fields are
+    empty."""
+    logo: int
+    """The logo shown with it: 0 the built-in logo, -1 none, 1 to 5 a slot."""
+    priority: OsdMessagePriority|int
+    """Where it stands against the unit's own messages."""
+    text: str
+    """Its markup."""
+
+    def __str__(self) -> str:
+        if (OsdMessageFlag.SET not in self.flags):
+            return f"none{' (refused)' if (OsdMessageFlag.REFUSED in self.flags) else ''}"
+        return f"'{self.text}' logo {self.logo} {self.flags!r}"
+
 @dataclass(frozen=True)
 class OsdSyncEntry:
     """One setting of an overlay sync this client sends."""
@@ -2767,16 +2804,25 @@ class OneIPDeviceSettings:
                               else previous._power_save_level),
             ptp_messages=previous._ptp_messages.merge(self._ptp_messages, valid))
 
-    def as_applied_to(self, reported:OneIPDeviceSetting) -> 'OneIPDeviceSettings':
+    def as_applied_to(self, reported:'OneIPDeviceSettings|OneIPDeviceSetting|None') -> 'OneIPDeviceSettings':
         """
-        This block limited to what a device takes from a write about it.
+        This block limited to what a device that reported reported takes from a
+        write about it.
 
         A device applies a setting only if it has it, a profile, PTP mode, PTP
         domain, power save level or PTP DSCP only within its range, a stream
-        TTL only when it is not 0, and never what only it can report about
-        itself.
+        TTL only when it is not 0, a rotation only by its own step, and never
+        what only it can report about itself. The step stays the device's.
+
+        reported may be only the bits the device reported, which says nothing
+        of its step, so a rotation other than 0 is then left out.
         """
-        valid = (self._valid & reported) & ~ONEIP_DEVICE_SETTINGS_REPORTED_ONLY
+        if (reported is None):
+            reported = OneIPDeviceSettings()
+        elif not isinstance(reported, OneIPDeviceSettings):
+            reported = OneIPDeviceSettings(valid=OneIPDeviceSetting(reported))
+        own = reported._ptp_messages
+        valid = (self._valid & reported._valid) & ~ONEIP_DEVICE_SETTINGS_REPORTED_ONLY
         if not (0 <= self._ir_profile < ONEIP_IR_PROFILE_MAX):
             valid &= ~OneIPDeviceSetting.IR_PROFILE
         if not (ONEIP_IR_PROFILE_NOT_SET <= self._ir_profile_sink < ONEIP_IR_PROFILE_MAX):
@@ -2791,13 +2837,16 @@ class OneIPDeviceSettings:
             valid &= ~OneIPDeviceSetting.PTP_DSCP
         if (self._ptp_messages.stream_ttl == 0):
             valid &= ~OneIPDeviceSetting.STREAM_TTL
+        if not own.takes_sink_rotation(self._ptp_messages.sink_rotation):
+            valid &= ~OneIPDeviceSetting.SINK_ROTATION
         return OneIPDeviceSettings(valid=valid, flags=self._flags, ir_profiles=self._ir_profiles,
                                   ir_profile=self._ir_profile, ir_profile_sink=self._ir_profile_sink,
                                   auto_power_save=self._auto_power_save, power_save=self._power_save,
                                   ptp_mode=self._ptp_mode, ptp_domain=self._ptp_domain,
                                   ptp_priority1=self._ptp_priority1,
                                   power_save_level=self._power_save_level,
-                                  ptp_messages=self._ptp_messages)
+                                  ptp_messages=replace(self._ptp_messages,
+                                                       sink_rotation_step=own.sink_rotation_step))
 
     def __eq__(self, other:Any) -> bool:
         if not isinstance(other, OneIPDeviceSettings):
@@ -3505,6 +3554,26 @@ class DeviceBase(ABC):
     def osd_sync_report(self) -> OsdSyncReport|None:
         '''This unit's last report on taking an overlay sync, None until it has.'''
 
+    @property
+    @abstractmethod
+    def osd_message(self) -> OsdMessage|None:
+        '''The message on this unit's output, as it last reported it to this
+        client, None until it has. A unit reports it only when asked, or when
+        this client writes it.'''
+
+    @abstractmethod
+    async def request_osd_message(self) -> bool:
+        '''ask this unit for the message on its output'''
+
+    @abstractmethod
+    async def show_osd_message(self, text:str, logo:int=-1,
+                               priority:OsdMessagePriority=OsdMessagePriority.NORMAL) -> bool:
+        '''show a message on this unit's output, in place of any it has'''
+
+    @abstractmethod
+    async def clear_osd_message(self) -> bool:
+        '''take the message down from this unit's output'''
+
     @property
     @abstractmethod
     def oneip_sink_sdp(self) -> OneIPSinkSdp|None:
@@ -4120,6 +4189,11 @@ class MxrCallbacks:
         _LOGGER.debug(f"{dev} overlay sync {report.seq}: {report.state!r} {report.reason}")
         self.on_device_update(dev)
 
+    def on_osd_message_changed(self, dev:DeviceBase, message:OsdMessage) -> None:
+        ''' called when unit 'dev' reported something different about the message on its output '''
+        _LOGGER.debug(f"{dev} overlay message: {message}")
+        self.on_device_update(dev)
+
     def on_osd_sync_requested(self, dev:DeviceBase, request:OsdSyncRequest) -> None:
         ''' called when 'dev' asked for an overlay sync, or for settings of one '''
         pass

{mx_remote-8.1.0 → mx_remote-9.0.0}/mx_remote/Interface.pyi

@@ -787,6 +787,9 @@ class OneIPPtpMessages:
     sap_expire_min: int = ...
     sap_interval_s: int = ...
     stream_ttl: int = ...
+    sink_rotation: int = ...
+    sink_rotation_step: int = ...
+    def takes_sink_rotation(self, degrees: int) -> bool: ...
     def merge(self, other: OneIPPtpMessages, which: OneIPDeviceSetting) -> OneIPPtpMessages: ...
     def describe(self, valid: OneIPDeviceSetting) -> list[str]: ...
 
@@ -853,6 +856,13 @@ class OsdSyncReport:
     refused: int
     reason: str
 
+@dataclass(frozen=True)
+class OsdMessage:
+    flags: OsdMessageFlag
+    logo: int
+    priority: OsdMessagePriority | int
+    text: str
+
 @dataclass(frozen=True)
 class OsdSyncEntry:
     value: OsdSyncValue
@@ -968,7 +978,7 @@ class OneIPDeviceSettings:
     @property
     def ptp_messages(self) -> OneIPPtpMessages | None: ...
     def merge(self, previous: OneIPDeviceSettings | None) -> OneIPDeviceSettings: ...
-    def as_applied_to(self, reported: OneIPDeviceSetting) -> OneIPDeviceSettings: ...
+    def as_applied_to(self, reported: OneIPDeviceSettings | OneIPDeviceSetting | None) -> OneIPDeviceSettings: ...
     def __eq__(self, other: Any) -> bool: ...
     def __ne__(self, other: Any) -> bool: ...
 
@@ -1324,6 +1334,15 @@ class DeviceBase(ABC):
     def osd_sync_report(self) -> OsdSyncReport | None: ...
     @property
     @abstractmethod
+    def osd_message(self) -> OsdMessage | None: ...
+    @abstractmethod
+    async def request_osd_message(self) -> bool: ...
+    @abstractmethod
+    async def show_osd_message(self, text: str, logo: int = -1, priority: OsdMessagePriority = ...) -> bool: ...
+    @abstractmethod
+    async def clear_osd_message(self) -> bool: ...
+    @property
+    @abstractmethod
     def oneip_sink_sdp(self) -> OneIPSinkSdp | None: ...
     @property
     @abstractmethod
@@ -1561,6 +1580,7 @@ class MxrCallbacks:
     def on_status_hdbt_connected_changed(self, bay: BayBase, val: bool) -> None: ...
     def on_osd_sync(self, dev: DeviceBase, sync: OsdSync) -> None: ...
     def on_osd_sync_report(self, dev: DeviceBase, report: OsdSyncReport) -> None: ...
+    def on_osd_message_changed(self, dev: DeviceBase, message: OsdMessage) -> None: ...
     def on_osd_sync_requested(self, dev: DeviceBase, request: OsdSyncRequest) -> None: ...
     def on_osd_sync_setting(self, dev: DeviceBase, setting: OsdSyncSetting) -> None: ...
     def on_bay_content_changed(self, bay: BayBase, content: BayContent) -> None: ...

{mx_remote-8.1.0 → mx_remote-9.0.0}/mx_remote/const.py

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

{mx_remote-8.1.0 → mx_remote-9.0.0}/mx_remote/proto/Constants.py

@@ -379,6 +379,9 @@ class OneIPDeviceSetting(IntFlag):
 	CLOUD              = (1 << 30)
 	'''Connects to the cloud service. A device that does not report it
 	connects regardless.'''
+	SINK_ROTATION      = (1 << 31)
+	'''The angle the device's HDMI output is turned by. Reported only by a
+	device with an HDMI output.'''
 
 ONEIP_DEVICE_SETTING_SWITCHES = OneIPDeviceSetting(0xFF) | OneIPDeviceSetting.AES67 \
 	| OneIPDeviceSetting.SAP_LISTEN | OneIPDeviceSetting.SAP_ANNOUNCE | OneIPDeviceSetting.POWER_SAVE_DISABLED \
@@ -398,14 +401,17 @@ ONEIP_DEVICE_SETTINGS_PTP_MESSAGES = OneIPDeviceSetting.PTP_ANNOUNCE | OneIPDevi
 """The PTP message settings."""
 
 ONEIP_DEVICE_SETTINGS_BLOCK = ONEIP_DEVICE_SETTINGS_PTP_MESSAGES | OneIPDeviceSetting.SAP_EXPIRE \
-	| OneIPDeviceSetting.SAP_INTERVAL | OneIPDeviceSetting.STREAM_TTL
+	| OneIPDeviceSetting.SAP_INTERVAL | OneIPDeviceSetting.STREAM_TTL | OneIPDeviceSetting.SINK_ROTATION
 """The settings whose values a frame carries in a block of their own behind the
-rest, OneIPPtpMessages: the PTP message settings, the two SAP values and the
-stream TTL."""
+rest, OneIPPtpMessages: the PTP message settings, the two SAP values, the
+stream TTL and the output's rotation."""
 
 ONEIP_STREAM_TTL_DEFAULT = 64
 """The TTL a OneIP device's streams carry until it is set."""
 
+ONEIP_SINK_ROTATION_MAX = 359
+"""The largest angle a OneIP device's HDMI output is turned by, in degrees."""
+
 class OneIPPtpMode(IntEnum):
 	'''How a OneIP device takes part in PTP.'''
 	OFF      = 0
@@ -434,6 +440,31 @@ class OsdSyncWhat(IntFlag):
 	LOGO_SLOTS  = (1 << 3)
 	'''The logo images in the four slots.'''
 
+class OsdMessageFlag(IntFlag):
+	'''What a unit says of the message on its output.'''
+	SET       = (1 << 0)
+	'''A message is set. In a write: show it, rather than take it down.'''
+	SHOWN     = (1 << 1)
+	'''The output shows it, rather than another message ahead of it.'''
+	SUPPORTED = (1 << 2)
+	'''The unit's video processor composes the message layer.'''
+	REFUSED   = (1 << 3)
+	'''The unit did not take the write it answers, and reports the message it
+	kept.'''
+
+class OsdMessagePriority(IntEnum):
+	'''Where a message stands against the unit's own messages: its upgrade,
+	Locate Device and encrypted source messages.'''
+	LOW    = 0
+	'''After them.'''
+	NORMAL = 1
+	'''Between them.'''
+	TOP    = 2
+	'''Before them.'''
+
+OSD_MESSAGE_TEXT_MAX = 255
+"""The longest message text a unit takes, in bytes."""
+
 class OsdSyncState(IntEnum):
 	'''How far a unit has got with taking an overlay sync.'''
 	TAKING   = 0

{mx_remote-8.1.0 → mx_remote-9.0.0}/mx_remote/proto/Constants.pyi

@@ -109,6 +109,7 @@ class OneIPDeviceSetting(IntFlag):
     POWER_SAVE_DISABLED: Incomplete
     STREAM_TTL: Incomplete
     CLOUD: Incomplete
+    SINK_ROTATION: Incomplete
 
 ONEIP_DEVICE_SETTING_SWITCHES: Incomplete
 ONEIP_DEVICE_SETTINGS_REPORTED_ONLY: Incomplete
@@ -116,6 +117,7 @@ ONEIP_DEVICE_SETTINGS_PTP: Incomplete
 ONEIP_DEVICE_SETTINGS_PTP_MESSAGES: Incomplete
 ONEIP_DEVICE_SETTINGS_BLOCK: Incomplete
 ONEIP_STREAM_TTL_DEFAULT: int
+ONEIP_SINK_ROTATION_MAX: int
 
 class OneIPPtpMode(IntEnum):
     OFF: int
@@ -132,6 +134,19 @@ class OsdSyncWhat(IntFlag):
     BACKGROUNDS: Incomplete
     LOGO_SLOTS: Incomplete
 
+class OsdMessageFlag(IntFlag):
+    SET: Incomplete
+    SHOWN: Incomplete
+    SUPPORTED: Incomplete
+    REFUSED: Incomplete
+
+class OsdMessagePriority(IntEnum):
+    LOW: int
+    NORMAL: int
+    TOP: int
+
+OSD_MESSAGE_TEXT_MAX: int
+
 class OsdSyncState(IntEnum):
     TAKING: int
     DONE: int

{mx_remote-8.1.0 → mx_remote-9.0.0}/mx_remote/proto/FrameV2IPDeviceConfiguration.py

@@ -133,7 +133,9 @@ SETTINGS_BLOCK_OFFSET = _PTP_STATE_OFFSET + _PTP_STATE_SIZE
 state.'''
 SETTINGS_BLOCK_SIZE = 8
 _STREAM_TTL_AT = 8
-_SETTINGS_BLOCK_TTL_SIZE = 16
+_SINK_ROTATION_AT = 10
+_SINK_ROTATION_STEP_AT = 12
+_SETTINGS_BLOCK_LONG_SIZE = 16
 
 def carries_settings_block(settings:OneIPDeviceSettings) -> bool:
     '''Whether settings carry a value only the block of their own can hold.'''
@@ -141,14 +143,24 @@ def carries_settings_block(settings:OneIPDeviceSettings) -> bool:
 
 def own_settings_block(settings:OneIPDeviceSettings) -> bytes:
     '''The block the settings in ONEIP_DEVICE_SETTINGS_BLOCK travel in: 8
-    bytes, or 16 with the stream TTL at 8 when the settings carry it.'''
+    bytes, or 16 when the settings carry the stream TTL, at 8, or the output's
+    rotation, a u16 at 10. Only a device that has either reads past 8, so a
+    frame without them keeps the length every device knows. The rotation's
+    step at 12 is the device's to report, and is left 0.'''
     m = settings.ptp_messages or OneIPPtpMessages()
     block = struct.pack('<bbbBBBH', m.log_announce_interval, m.log_sync_interval,
                         m.log_delay_req_interval, m.announce_timeout, m.dscp, m.sap_expire_min,
                         m.sap_interval_s)
-    if (OneIPDeviceSetting.STREAM_TTL in settings.valid):
-        block += bytes([m.stream_ttl]).ljust(_SETTINGS_BLOCK_TTL_SIZE - len(block), b'\0')
-    return block
+    ttl = (OneIPDeviceSetting.STREAM_TTL in settings.valid)
+    rotation = (OneIPDeviceSetting.SINK_ROTATION in settings.valid)
+    if not (ttl or rotation):
+        return block
+    tail = bytearray(_SETTINGS_BLOCK_LONG_SIZE - len(block))
+    if ttl:
+        tail[_STREAM_TTL_AT - len(block)] = m.stream_ttl
+    if rotation:
+        struct.pack_into('<H', tail, _SINK_ROTATION_AT - len(block), m.sink_rotation)
+    return block + bytes(tail)
 
 def parse_own_settings_block(block:bytes, valid:OneIPDeviceSetting) -> tuple[OneIPPtpMessages, OneIPDeviceSetting]:
     '''The block the settings in ONEIP_DEVICE_SETTINGS_BLOCK travel in, and
@@ -158,10 +170,16 @@ def parse_own_settings_block(block:bytes, valid:OneIPDeviceSetting) -> tuple[One
     if (len(block) <= _STREAM_TTL_AT):
         valid &= ~OneIPDeviceSetting.STREAM_TTL
     ttl = block[_STREAM_TTL_AT] if (len(block) > _STREAM_TTL_AT) else 0
+    rotation, step = 0, 0
+    if (len(block) >= _SINK_ROTATION_STEP_AT + 2):
+        rotation, step = struct.unpack_from('<HH', block, _SINK_ROTATION_AT)
+    else:
+        valid &= ~OneIPDeviceSetting.SINK_ROTATION
     announce, sync, delay_req, timeout, dscp, expire, interval = struct.unpack_from('<bbbBBBH', block)
     return (OneIPPtpMessages(log_announce_interval=announce, log_sync_interval=sync,
                              log_delay_req_interval=delay_req, announce_timeout=timeout, dscp=dscp,
-                             sap_expire_min=expire, sap_interval_s=interval, stream_ttl=ttl), valid)
+                             sap_expire_min=expire, sap_interval_s=interval, stream_ttl=ttl,
+                             sink_rotation=rotation, sink_rotation_step=step), valid)
 
 def settings_block(settings:OneIPDeviceSettings) -> bytes:
     '''The 48-byte device settings block.
@@ -520,8 +538,7 @@ class FrameV2IPDeviceConfiguration(FrameBase):
         frame = parse_settings_block(self.payload[_SETTINGS_OFFSET:], self.payload[SETTINGS_BLOCK_OFFSET:])
         if self.target_self:
             return frame
-        reported = dev.oneip_settings
-        return frame.as_applied_to(reported.valid if (reported is not None) else OneIPDeviceSetting(0))
+        return frame.as_applied_to(dev.oneip_settings)
 
     @cached_property
     def vlan(self) -> OneIPVlan|None:

{mx_remote-8.1.0 → mx_remote-9.0.0}/mx_remote/proto/FrameV2IPOsdSync.py

@@ -17,12 +17,14 @@ sync carries the same seq, which the source numbers on its own.
 from functools import cached_property
 import ipaddress
 import struct
+from typing import Any
 import zlib
 from ..compat import override
 from .Constants import (OSD_SYNC_RECORDS_MAX, OSD_SYNC_SLOTS, DeviceFeature, OsdCaptionAlign,
-                        OsdCaptionFormat, OsdSyncSize, OsdSyncState, OsdSyncWhat)
+                        OsdCaptionFormat, OsdMessageFlag, OsdMessagePriority, OsdSyncSize, OsdSyncState,
+                        OsdSyncWhat)
 from .FrameBase import FrameBase
-from ..Interface import (DeviceRegistry, OsdCaption, OsdLogo, OsdSync, OsdSyncEntry, OsdSyncReport,
+from ..Interface import (DeviceRegistry, OsdCaption, OsdLogo, OsdMessage, OsdSync, OsdSyncEntry, OsdSyncReport,
                          OsdSyncRequest, OsdSyncSetting, OsdSyncSlot, OsdSyncValue, _wire_enum)
 from ..Uid import MxrDeviceUid
 
@@ -32,13 +34,16 @@ from ..Uid import MxrDeviceUid
 #   sync     what at 20, u16 HTTP port at 22, the source's IPv4 address at 24,
 #            u16 records at 28, then four 12-byte logo slots from 32 (u32
 #            bytes, u32 CRC-32, u8 percent): 80 bytes
-#   request  what at 20, the 16-byte missing-settings bitmap at 22, then from
-#            54 the sync's source, which units on an older overlay module do
-#            not send: 38 or 54 bytes
+#   request  what at 20, the 16-byte missing-settings bitmap at 22, then the
+#            sync's source at 38: 54 bytes
 #   setting  u16 index at 20, u16 records at 22, kind at 24, size at 25, u16
 #            layers at 26, u16 set at 28, then the body at 30
 #   report   state at 20, u16 written at 22, u16 refused at 24, a 64-byte
 #            reason at 26: 90 bytes
+#   message  flags at 20, logo at 21, priority at 22, a reserved byte, u16 text
+#            length at 24, then the text, unterminated, with a seq of 0: a
+#            request for the message on the unit's output, a write of one, or
+#            the unit's answer to either
 OSD_SYNC_VERSION = 2
 '''The payload version every frame opens with; a unit drops any other.'''
 _HEADER_SIZE = 20
@@ -47,14 +52,18 @@ OSD_KIND_SYNC = 0
 OSD_KIND_REQUEST = 1
 OSD_KIND_SETTING = 2
 OSD_KIND_REPORT = 3
+OSD_KIND_MESSAGE_REQUEST = 4
+OSD_KIND_MESSAGE_SET = 5
+OSD_KIND_MESSAGE_STATE = 6
 
 _SYNC_SIZE = 80
 _SLOTS_AT = 32
 _SLOT_SIZE = 12
-_REQUEST_SIZE = 38
+_REQUEST_SIZE = 54
 _REQUEST_SOURCE_AT = 38
 _SETTING_BODY_AT = 30
 _REPORT_SIZE = 90
+_MESSAGE_SIZE = 26
 
 OSD_SETTING_CAPTION = 0
 OSD_SETTING_LOGO = 1
@@ -114,6 +123,15 @@ class FrameV2IPOsdSync(FrameBase):
             p += struct.pack('<I', value)
         return FrameBase.construct_base(mxr=mxr, opcode=0x53, payload=p, target=to)
 
+    @staticmethod
+    def construct_message(mxr:DeviceRegistry, target:Any, target_uid:MxrDeviceUid, kind:int,
+                          flags:OsdMessageFlag=OsdMessageFlag(0), logo:int=0,
+                          priority:OsdMessagePriority=OsdMessagePriority.LOW, text:bytes=b'') -> FrameBase|None:
+        '''A message frame of kind for the output of target_uid.'''
+        p = (_header(kind, 0, target_uid) + struct.pack('<BbBxH', int(flags), logo, int(priority), len(text))
+             + text)
+        return FrameBase.construct_base(target=target, mxr=mxr, opcode=0x53, payload=p)
+
     @cached_property
     def kind(self) -> int|None:
         '''The kind, None for a frame a unit drops: shorter than its header, or
@@ -168,15 +186,14 @@ class FrameV2IPOsdSync(FrameBase):
     def request(self) -> OsdSyncRequest|None:
         '''The request, None for any other kind or one no unit takes. A unit
         asks about itself; management may also ask for a new sync for another
-        unit. A request carries the sync's source from 54 bytes; a 38-byte one,
-        as units on an older module send, reads its source as empty.'''
+        unit.'''
         p = self.payload or b''
         if (self.kind != OSD_KIND_REQUEST) or (len(p) < _REQUEST_SIZE):
             return None
         target, seq = self.target, self.seq or 0
         if (target != self.remote_id) and not ((seq == 0) and self.from_management):
             return None
-        source = MxrDeviceUid(p[_REQUEST_SOURCE_AT:_REQUEST_SOURCE_AT + 16].ljust(16, b'\0'))
+        source = MxrDeviceUid(p[_REQUEST_SOURCE_AT:_REQUEST_SOURCE_AT + 16])
         return OsdSyncRequest(target=target, seq=seq, what=OsdSyncWhat(p[20]), missing=bytes(p[22:38]),
                               source=source)
 
@@ -223,29 +240,45 @@ class FrameV2IPOsdSync(FrameBase):
         return OsdSyncReport(seq=self.seq or 0, state=_wire_enum(OsdSyncState, p[20]), written=written,
                              refused=refused, reason=_cstr(p[26:_REPORT_SIZE]))
 
+    @cached_property
+    def message(self) -> OsdMessage|None:
+        '''The message a unit reports on its own output, None for any other
+        kind, one about another unit, or one short of the text it counts.'''
+        p = self.payload or b''
+        if (self.kind != OSD_KIND_MESSAGE_STATE) or (len(p) < _MESSAGE_SIZE) or (self.target != self.remote_id):
+            return None
+        flags, logo, priority, length = struct.unpack_from('<BbBxH', p, 20)
+        text = p[_MESSAGE_SIZE:]
+        if (len(text) < length):
+            return None
+        return OsdMessage(flags=OsdMessageFlag(flags), logo=logo, priority=_wire_enum(OsdMessagePriority, priority),
+                          text=text[:length].decode('utf-8', errors='replace'))
+
     @override
     def process(self) -> None:
         '''Record a sync and a report against their sender, and hand a request
         and a setting to the callbacks. A request this client may answer goes
         to the registry: one asking for a new sync, or one naming this client
-        as the source, or, from an older overlay module, naming none.'''
+        as the source.'''
         if ((dev := self.remote_device) is None):
             return
         if ((sync := self.sync) is not None):
             dev.on_mxr_update(sync)
         elif ((report := self.report) is not None):
             dev.on_mxr_update(report)
+        elif ((message := self.message) is not None):
+            dev.on_mxr_update(message)
         elif ((setting := self.setting) is not None):
             dev.callbacks.on_osd_sync_setting(dev, setting)
         elif ((request := self.request) is not None):
             dev.callbacks.on_osd_sync_requested(dev, request)
-            if (request.seq == 0) or request.source.empty or (request.source == self.mxr.uid):
+            if (request.seq == 0) or (request.source == self.mxr.uid):
                 self.mxr.on_mxr_update(request)
 
     def __str__(self) -> str:
         if (self.kind is None):
             return "overlay sync <dropped>"
-        for item in (self.sync, self.request, self.setting, self.report):
+        for item in (self.sync, self.request, self.setting, self.report, self.message):
             if (item is not None):
                 return f"overlay sync {item}"
         return f"overlay sync kind {self.kind} seq {self.seq} not taken"