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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mx_remote
-Version: 9.2.0
+Version: 9.3.0
 Summary: Python 3 library for interfacing with MX Remote compatible devices
 Project-URL: Homepage, https://github.com/opdenkamp/mx-remote/
 Project-URL: Documentation, https://opdenkamp.github.io/mx-remote/

{mx_remote-9.2.0 → mx_remote-9.3.0}/docs/api.md

@@ -288,6 +288,23 @@ How a source unit encrypts its streams, as it reports it.
    :members:
 ```
 
+## Application messages
+
+Messages applications exchange over the mesh under their own vendor id.
+
+```{eval-rst}
+.. autoclass:: mx_remote.ThirdPartyMessage
+   :members:
+
+.. autoclass:: mx_remote.ThirdPartyVendor
+   :members:
+
+.. autoclass:: mx_remote.proto.Constants.ThirdPartyVendorFlag
+   :members:
+
+.. autodata:: mx_remote.proto.Constants.THIRD_PARTY_PAYLOAD_MAX
+```
+
 ## OneIP test card
 
 A sink's test pattern, tone and lip-sync flash, and the ranges it accepts.

{mx_remote-9.2.0 → mx_remote-9.3.0}/docs/callbacks.md

@@ -67,6 +67,7 @@ Available callback methods:
 | `on_rc_type_changed` | remote control type changed |
 | `on_amp_zone_settings_changed` | amplifier zone settings changed |
 | `on_amp_dolby_settings_changed` | amplifier Dolby settings changed |
+| `on_third_party_message` | another application sent a message under its vendor id |
 
 You can also register per-device and per-bay callbacks:
 
@@ -85,6 +86,30 @@ device.unregister_callback(on_device_changed)
 bay.unregister_callback(on_bay_changed)
 ```
 
+## Application messages
+
+Applications built on this library can message each other over the mesh. A
+message carries a vendor id, then up to `THIRD_PARTY_PAYLOAD_MAX` (1444) bytes
+that only the application reads. The vendor id is the vendor's IEEE OUI, or an
+identifier it chose, such as three letters:
+
+```python
+from mx_remote import ThirdPartyVendor
+
+ODK = ThirdPartyVendor.private(b'ODK')
+
+await mx.send_third_party(ODK, b'hello')    # False when over 1444 bytes
+
+class MyCallbacks(mx_remote.MxrCallbacks):
+    def on_third_party_message(self, dev, message):
+        if message.vendor.same_vendor(ODK):
+            print(f"{dev} says {message.payload!r}")
+```
+
+Every other client that has heard this one announce itself receives the
+message; this client does not. No unit reads it, and nothing acknowledges it,
+so an application that needs to know a message arrived has its peers answer.
+
 ---
 
 [Documentation index](README.md) | [Project README](https://github.com/opdenkamp/mx-remote#readme)

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

@@ -2601,6 +2601,68 @@ class OneIPPrivacy:
     def __str__(self) -> str:
         return f"video {self.video}, audio {self.audio}, anc {self.anc}"
 
+@dataclass(frozen=True)
+class ThirdPartyVendor:
+    """
+    Whose message a third-party message is: a flag byte, then three bytes
+    naming the vendor.
+
+    The three bytes are the vendor's IEEE OUI, in the order it is written, or
+    with ThirdPartyVendorFlag.NOT_OUI set an identifier of the vendor's own
+    choosing, such as three ASCII letters. The flag keeps the two spaces apart,
+    so a chosen identifier never collides with a registered OUI.
+    """
+    flags: ThirdPartyVendorFlag
+    """The flag byte, at offset 0."""
+    id: bytes
+    """The vendor's three identifying bytes, at offsets 1 to 3."""
+
+    def __post_init__(self) -> None:
+        if (len(self.id) != 3):
+            raise ValueError(f"a vendor id is 3 bytes, not {len(self.id)}")
+
+    @classmethod
+    def oui(cls, oui:bytes) -> 'ThirdPartyVendor':
+        """A vendor named by its IEEE OUI."""
+        return cls(flags=ThirdPartyVendorFlag(0), id=bytes(oui))
+
+    @classmethod
+    def private(cls, id:bytes) -> 'ThirdPartyVendor':
+        """A vendor named by an identifier it chose, rather than an OUI."""
+        return cls(flags=ThirdPartyVendorFlag.NOT_OUI, id=bytes(id))
+
+    def same_vendor(self, other:'ThirdPartyVendor') -> bool:
+        """Whether other names the same vendor.
+
+        Only ThirdPartyVendorFlag.NOT_OUI and the three identifying bytes say
+        who the vendor is, so the other flag bits are left out."""
+        return ((ThirdPartyVendorFlag.NOT_OUI in self.flags) == (ThirdPartyVendorFlag.NOT_OUI in other.flags)) \
+            and (self.id == other.id)
+
+    def __str__(self) -> str:
+        if (ThirdPartyVendorFlag.NOT_OUI in self.flags):
+            return f"vendor {self.id!r}"
+        return f"vendor OUI {self.id.hex(':')}"
+
+@dataclass(frozen=True)
+class ThirdPartyMessage:
+    """
+    A message an application sent to every device, under its own vendor id.
+
+    The library reads only the vendor id. What follows is the application's,
+    and arrives exactly as it was sent.
+    """
+    vendor: ThirdPartyVendor
+    """Which application's message this is. The library checks none: each
+    application ignores every message whose vendor is not its own."""
+    payload: bytes
+    """The application's bytes, at most THIRD_PARTY_PAYLOAD_MAX."""
+    address: str|None
+    """Where the datagram came from."""
+
+    def __str__(self) -> str:
+        return f"{self.vendor}: {len(self.payload)} bytes"
+
 @dataclass(frozen=True)
 class OneIPTestTone:
     """A OneIP sink's test tone."""
@@ -4370,6 +4432,13 @@ class MxrCallbacks:
         _LOGGER.debug(f"{device} dolby settings changed")
         self.on_device_update(device)
 
+    def on_third_party_message(self, dev:DeviceBase, message:ThirdPartyMessage) -> None:
+        ''' called when the application on 'dev' sent a message under its own
+        vendor id. A message from a sender this client has not yet heard
+        announce itself is dropped, as every frame is, and this client never
+        receives its own. '''
+        pass
+
 # The V2IP spelling of a name here, from before the rename to OneIP.
 from .deprecated import alias_members as _alias_members, module_getattr as _module_getattr
 # Installed through globals() so the generated stubs carry no __getattr__, which

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

@@ -930,6 +930,23 @@ class OneIPPrivacy:
     audio: OneIPPrivacyStream
     anc: OneIPPrivacyStream
 
+@dataclass(frozen=True)
+class ThirdPartyVendor:
+    flags: ThirdPartyVendorFlag
+    id: bytes
+    def __post_init__(self) -> None: ...
+    @classmethod
+    def oui(cls, oui: bytes) -> ThirdPartyVendor: ...
+    @classmethod
+    def private(cls, id: bytes) -> ThirdPartyVendor: ...
+    def same_vendor(self, other: ThirdPartyVendor) -> bool: ...
+
+@dataclass(frozen=True)
+class ThirdPartyMessage:
+    vendor: ThirdPartyVendor
+    payload: bytes
+    address: str | None
+
 @dataclass(frozen=True)
 class OneIPTestTone:
     mode: OneIPToneMode | int = ...
@@ -1620,3 +1637,4 @@ class MxrCallbacks:
     def on_rc_type_changed(self, bay: BayBase, rc_type: RCType | None) -> None: ...
     def on_amp_zone_settings_changed(self, bay: BayBase, settings: AmpZoneSettings) -> None: ...
     def on_amp_dolby_settings_changed(self, device: DeviceBase, settings: AmpDolbySettings) -> None: ...
+    def on_third_party_message(self, dev: DeviceBase, message: ThirdPartyMessage) -> None: ...

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

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

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

@@ -123,6 +123,9 @@ MXR_OPCODE_VERSIONS: dict[int, int] = {
     0x52: 0x2E,  # V2IP_SINK_SDP
     0x53: 0x2F,  # V2IP_OSD_SYNC
     0x54: 0x30,  # V2IP_PRIVACY
+    # The lowest stamp, so that every receiver's ceiling passes it. No device
+    # decodes the payload, so there is no layout for a stamp to announce.
+    0x55: 0x01,  # THIRD_PARTY
 }
 """Per-opcode minimum compatible protocol version, mirroring the firmware's
 own opcode table. Transmitters stamp the
@@ -822,6 +825,21 @@ ONEIP_VLAN_PORT_SFP = 0
 ONEIP_VLAN_ID_MAX = 4094
 """The highest VLAN id: 0 means untagged, and 4095 is reserved by IEEE 802.1Q."""
 
+class ThirdPartyVendorFlag(IntFlag):
+	'''The first byte of a third-party vendor id, ahead of its three
+	identifying bytes. Bits without a name are kept as they arrived.'''
+	NOT_OUI = (1 << 0)
+	'''The three bytes are an identifier the vendor chose, rather than its
+	IEEE OUI.'''
+
+THIRD_PARTY_PAYLOAD_MAX = 1444
+"""The largest payload a third-party message carries.
+
+A frame this size fills one 1500-byte Ethernet frame exactly: 20 bytes of IPv4
+header, 8 of UDP, the 24-byte frame header and the 4-byte vendor id leave 1444.
+A larger send is refused rather than fragmented, because a lost fragment loses
+the whole datagram and nothing on these paths retries."""
+
 BAY_FEATURE_DOLBY_IN_POS = 24
 
 class BayFeaturesMask(IntFlag):

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

@@ -340,6 +340,11 @@ class OneIPVlanFlag(IntFlag):
 ONEIP_VLAN_PORTS: int
 ONEIP_VLAN_PORT_SFP: int
 ONEIP_VLAN_ID_MAX: int
+
+class ThirdPartyVendorFlag(IntFlag):
+    NOT_OUI: Incomplete
+
+THIRD_PARTY_PAYLOAD_MAX: int
 BAY_FEATURE_DOLBY_IN_POS: int
 
 class BayFeaturesMask(IntFlag):

{mx_remote-9.2.0 → mx_remote-9.3.0}/mx_remote/proto/Factory.py

@@ -249,6 +249,9 @@ def _mxr_frame_factory(hdr:FrameHeader, timestamp:float) -> FrameBase|None:
 	if hdr.opcode == 0x54:
 		from .FrameV2IPPrivacy import FrameV2IPPrivacy
 		return FrameV2IPPrivacy(header=hdr, timestamp=timestamp)
+	if hdr.opcode == 0x55:
+		from .FrameThirdParty import FrameThirdParty
+		return FrameThirdParty(header=hdr, timestamp=timestamp)
 	if hdr.opcode == 0x50:
 		from .FrameUnitCommand import FrameUnitCommand
 		return FrameUnitCommand(header=hdr, timestamp=timestamp)

mx_remote-9.3.0/mx_remote/proto/FrameThirdParty.py

@@ -0,0 +1,50 @@
+######################################################
+##            MX Remote Python Interface            ##
+##                                                  ##
+## author: Lars Op den Kamp (lars@opdenkamp-it.nl)  ##
+## copyright (c) 2021-2026 Op den Kamp IT Solutions ##
+######################################################
+'''Protocol frame for THIRD_PARTY (opcode 0x55): messages applications
+exchange over the mesh.'''
+
+from functools import cached_property
+from ..compat import override
+from .Constants import ThirdPartyVendorFlag
+from .FrameBase import FrameBase
+from ..Interface import DeviceRegistry, ThirdPartyMessage, ThirdPartyVendor
+
+# The flag byte at 0 and the three identifying bytes at 1, then the
+# application's bytes to the end of the frame.
+VENDOR_SIZE = 4
+
+class FrameThirdParty(FrameBase):
+	'''An application's own message, under its vendor id.'''
+	@staticmethod
+	def construct(mxr:DeviceRegistry, vendor:ThirdPartyVendor, payload:bytes) -> FrameBase|None:
+		'''A message to every device: the vendor's flag byte and three
+		identifying bytes, then payload as it was given.'''
+		data = bytes([int(vendor.flags)]) + vendor.id + bytes(payload)
+		return FrameBase.construct_base(mxr=mxr, opcode=0x55, payload=data)
+
+	@cached_property
+	def message(self) -> ThirdPartyMessage|None:
+		'''The message, whatever its vendor: telling them apart is the
+		application's. None for a payload too short for the vendor id.
+		Everything after the id is the application's, so the length is a
+		minimum and nothing past it is read.'''
+		p = self.payload or b''
+		if (len(p) < VENDOR_SIZE):
+			return None
+		vendor = ThirdPartyVendor(flags=ThirdPartyVendorFlag(p[0]), id=bytes(p[1:VENDOR_SIZE]))
+		return ThirdPartyMessage(vendor=vendor, payload=bytes(p[VENDOR_SIZE:]), address=self.address)
+
+	@override
+	def process(self) -> None:
+		'''Hand the message to the callbacks, as sent by the device it came from.'''
+		if ((message := self.message) is not None) and ((dev := self.remote_device) is not None):
+			dev.callbacks.on_third_party_message(dev, message)
+
+	def __str__(self) -> str:
+		if (self.message is None):
+			return "third-party message <dropped>"
+		return f"third-party message from {self.message}"

mx_remote-9.3.0/mx_remote/proto/FrameThirdParty.pyi

@@ -0,0 +1,15 @@
+from ..Interface import DeviceRegistry as DeviceRegistry, ThirdPartyMessage as ThirdPartyMessage, ThirdPartyVendor as ThirdPartyVendor
+from ..compat import override as override
+from .Constants import ThirdPartyVendorFlag as ThirdPartyVendorFlag
+from .FrameBase import FrameBase as FrameBase
+from functools import cached_property
+
+VENDOR_SIZE: int
+
+class FrameThirdParty(FrameBase):
+    @staticmethod
+    def construct(mxr: DeviceRegistry, vendor: ThirdPartyVendor, payload: bytes) -> FrameBase | None: ...
+    @cached_property
+    def message(self) -> ThirdPartyMessage | None: ...
+    @override
+    def process(self) -> None: ...

{mx_remote-9.2.0 → mx_remote-9.3.0}/mx_remote/remote/Remote.py

@@ -22,12 +22,13 @@ from datetime import datetime, timezone
 from .ConnectionAsync import ConnectionAsync
 from ..const import MXR_HELLO_INTERVAL_MIN, MXR_HELLO_INTERVAL_RAND, __version__
 from .Device import Device
-from ..Interface import ConnectionCallbacks, DeviceRegistry, MxrDeviceUid, BayLinks, BayBase, DeviceBase, MxrCallbacks, AudioEndpoint, mxr_broadcast_address, OneIPDeviceSettings, OneIPPowerSaveSchedule, OneIPPtpMessages, OsdSyncContent, OsdSyncRequest
-from ..proto.Constants import MXR_PROTOCOL_VERSION, DeviceFeature, OsdSyncWhat
+from ..Interface import ConnectionCallbacks, DeviceRegistry, MxrDeviceUid, BayLinks, BayBase, DeviceBase, MxrCallbacks, AudioEndpoint, mxr_broadcast_address, OneIPDeviceSettings, OneIPPowerSaveSchedule, OneIPPtpMessages, OsdSyncContent, OsdSyncRequest, ThirdPartyVendor
+from ..proto.Constants import MXR_PROTOCOL_VERSION, THIRD_PARTY_PAYLOAD_MAX, DeviceFeature, OsdSyncWhat
 from ..proto.FrameDiscover import FrameDiscover, constructFrameDiscover
 from ..proto.Factory import process_mxr_frame
 from ..proto.FrameHello import FrameHello, constructFrameHello
 from ..proto.FramePing import FramePing
+from ..proto.FrameThirdParty import FrameThirdParty
 from ..proto.FrameBase import FrameBase
 from ..proto.FrameTime import FrameTime
 from ..proto.FrameTimeZone import FrameTimeZone
@@ -573,6 +574,23 @@ class Remote(DeviceRegistry, ConnectionCallbacks):
         protocol 0x30 ignores it.'''
         return self._send_to_all(FrameV2IPPrivacy.construct_request(mxr=self, target=None, target_uid=None))
 
+    async def send_third_party(self, vendor:ThirdPartyVendor, payload:bytes) -> bool:
+        '''Send an application's own message to every device, under vendor.
+        True when all of it was written.
+
+        Every other client of this library that has heard this one announce
+        itself receives it at MxrCallbacks.on_third_party_message(); this client
+        does not, and neither does one sharing its uid. No unit is meant to read
+        it. Nothing acknowledges it, so an application that needs to know it
+        arrived has to have its peers answer.
+
+        A payload over THIRD_PARTY_PAYLOAD_MAX bytes is refused.'''
+        if (len(payload) > THIRD_PARTY_PAYLOAD_MAX):
+            _LOGGER.warning(f"not sending a third-party message: {len(payload)} bytes, "
+                            f"the most is {THIRD_PARTY_PAYLOAD_MAX}")
+            return False
+        return self._send_to_all(FrameThirdParty.construct(mxr=self, vendor=vendor, payload=payload))
+
     async def set_mesh_time_zone(self, zone:str, rule:str) -> bool:
         '''Set the time zone of every device that hears it.
 

{mx_remote-9.2.0 → mx_remote-9.3.0}/mx_remote/remote/Remote.pyi

@@ -1,14 +1,15 @@
 import aiohttp
-from ..Interface import AudioEndpoint as AudioEndpoint, BayBase as BayBase, BayLinks as BayLinks, ConnectionCallbacks as ConnectionCallbacks, DeviceBase as DeviceBase, DeviceRegistry as DeviceRegistry, MxrCallbacks as MxrCallbacks, OneIPDeviceSettings as OneIPDeviceSettings, OneIPPowerSaveSchedule as OneIPPowerSaveSchedule, OneIPPtpMessages as OneIPPtpMessages, OsdSyncContent as OsdSyncContent, OsdSyncRequest as OsdSyncRequest, mxr_broadcast_address as mxr_broadcast_address
+from ..Interface import AudioEndpoint as AudioEndpoint, BayBase as BayBase, BayLinks as BayLinks, ConnectionCallbacks as ConnectionCallbacks, DeviceBase as DeviceBase, DeviceRegistry as DeviceRegistry, MxrCallbacks as MxrCallbacks, OneIPDeviceSettings as OneIPDeviceSettings, OneIPPowerSaveSchedule as OneIPPowerSaveSchedule, OneIPPtpMessages as OneIPPtpMessages, OsdSyncContent as OsdSyncContent, OsdSyncRequest as OsdSyncRequest, ThirdPartyVendor as ThirdPartyVendor, mxr_broadcast_address as mxr_broadcast_address
 from ..Uid import MxrDeviceUid as MxrDeviceUid
 from ..compat import override as override
 from ..const import MXR_HELLO_INTERVAL_MIN as MXR_HELLO_INTERVAL_MIN, MXR_HELLO_INTERVAL_RAND as MXR_HELLO_INTERVAL_RAND, MX_BCAST_UDP_PORT as MX_BCAST_UDP_PORT, MX_MCAST_UDP_IP as MX_MCAST_UDP_IP, MX_MCAST_UDP_PORT as MX_MCAST_UDP_PORT, __version__ as __version__
-from ..proto.Constants import DeviceFeature as DeviceFeature, MXR_PROTOCOL_VERSION as MXR_PROTOCOL_VERSION, ONEIP_DEVICE_SETTINGS_REPORTED_ONLY as ONEIP_DEVICE_SETTINGS_REPORTED_ONLY, ONEIP_DSCP_MAX as ONEIP_DSCP_MAX, ONEIP_IR_PROFILE_MAX as ONEIP_IR_PROFILE_MAX, ONEIP_IR_PROFILE_NOT_SET as ONEIP_IR_PROFILE_NOT_SET, ONEIP_PTP_DOMAIN_MAX as ONEIP_PTP_DOMAIN_MAX, ONEIP_SINK_ROTATION_MAX as ONEIP_SINK_ROTATION_MAX, OneIPDeviceSetting as OneIPDeviceSetting, OneIPPowerSaveLevel as OneIPPowerSaveLevel, OneIPPtpMode as OneIPPtpMode, OsdSyncWhat as OsdSyncWhat
+from ..proto.Constants import DeviceFeature as DeviceFeature, MXR_PROTOCOL_VERSION as MXR_PROTOCOL_VERSION, ONEIP_DEVICE_SETTINGS_REPORTED_ONLY as ONEIP_DEVICE_SETTINGS_REPORTED_ONLY, ONEIP_DSCP_MAX as ONEIP_DSCP_MAX, ONEIP_IR_PROFILE_MAX as ONEIP_IR_PROFILE_MAX, ONEIP_IR_PROFILE_NOT_SET as ONEIP_IR_PROFILE_NOT_SET, ONEIP_PTP_DOMAIN_MAX as ONEIP_PTP_DOMAIN_MAX, ONEIP_SINK_ROTATION_MAX as ONEIP_SINK_ROTATION_MAX, OneIPDeviceSetting as OneIPDeviceSetting, OneIPPowerSaveLevel as OneIPPowerSaveLevel, OneIPPtpMode as OneIPPtpMode, OsdSyncWhat as OsdSyncWhat, THIRD_PARTY_PAYLOAD_MAX as THIRD_PARTY_PAYLOAD_MAX
 from ..proto.Factory import process_mxr_frame as process_mxr_frame
 from ..proto.FrameBase import FrameBase as FrameBase
 from ..proto.FrameDiscover import FrameDiscover as FrameDiscover, constructFrameDiscover as constructFrameDiscover
 from ..proto.FrameHello import FrameHello as FrameHello, constructFrameHello as constructFrameHello
 from ..proto.FramePing import FramePing as FramePing
+from ..proto.FrameThirdParty import FrameThirdParty as FrameThirdParty
 from ..proto.FrameTime import FrameTime as FrameTime
 from ..proto.FrameTimeZone import FrameTimeZone as FrameTimeZone
 from ..proto.FrameV2IPOsdSync import FrameV2IPOsdSync as FrameV2IPOsdSync
@@ -75,6 +76,7 @@ class Remote(DeviceRegistry, ConnectionCallbacks):
     async def set_all_oneip_device_settings(self, settings: OneIPDeviceSettings) -> bool: ...
     async def set_all_oneip_power_save(self, enabled: bool) -> bool: ...
     async def request_all_oneip_privacy(self) -> bool: ...
+    async def send_third_party(self, vendor: ThirdPartyVendor, payload: bytes) -> bool: ...
     async def set_mesh_time_zone(self, zone: str, rule: str) -> bool: ...
     async def clear_mesh_time_zone(self) -> bool: ...
     async def set_mesh_time(self, when: datetime | None = None) -> bool: ...

{mx_remote-9.2.0 → mx_remote-9.3.0}/tests/handlers.py

@@ -63,6 +63,7 @@ BASELINE = {
     'FrameSystemStatus.FrameSystemStatus',
     'FrameTXRCAction.FrameTXRCAction',
     'FrameTXRCKey.FrameTXRCKey',
+    'FrameThirdParty.FrameThirdParty',
     'FrameTime.FrameTime',
     'FrameTimeZone.FrameTimeZone',
     'FrameTopology.FrameTopology',

{mx_remote-9.2.0 → mx_remote-9.3.0}/tests/run.py

@@ -59,6 +59,7 @@ SUITES = [
     'meshbays',     # the bays a unit lists for other units, from its mappings
     'v2ipsdp',      # what a OneIP output plays from a session description
     'privacy',      # how a OneIP source unit encrypts its streams
+    'thirdparty',   # applications' own messages, sent and received
     'baycontent',   # what the source on an input is showing
     'osdsync',      # overlay sync, watched and sent
     'osdmessage',   # the message on a unit's output, read and written

{mx_remote-9.2.0 → mx_remote-9.3.0}/tests/smoke.py

@@ -12,6 +12,7 @@ print('version', mx_remote.const.VERSION, 'proto', hex(MXR_PROTOCOL_VERSION))
 assert MXR_PROTOCOL_VERSION == max(MXR_OPCODE_VERSIONS.values()), hex(MXR_PROTOCOL_VERSION)
 assert MXR_OPCODE_VERSIONS[0x52] == 0x2E and MXR_OPCODE_VERSIONS[0x53] == 0x2F  # V2IP_SINK_SDP, V2IP_OSD_SYNC
 assert MXR_OPCODE_VERSIONS[0x54] == 0x30  # V2IP_PRIVACY
+assert MXR_OPCODE_VERSIONS[0x55] == 0x01  # THIRD_PARTY
 assert MXR_OPCODE_VERSIONS[0x49] == 0x28 and MXR_OPCODE_VERSIONS[0x3C] == 0x11
 assert MXR_OPCODE_VERSIONS[0x4F] == 0x2C and MXR_OPCODE_VERSIONS[0x50] == 0x2C  # SYS_UNIT_STATUS, SYS_UNIT_COMMAND
 assert DeviceFeature.VIDEO_WALL == (1 << 24)

mx_remote-9.3.0/tests/thirdparty.py

@@ -0,0 +1,146 @@
+######################################################
+##            MX Remote Python Interface            ##
+##                                                  ##
+## author: Lars Op den Kamp (lars@opdenkamp-it.nl)  ##
+## copyright (c) 2021-2026 Op den Kamp IT Solutions ##
+######################################################
+'''Applications' own messages (0x55), sent and received.
+
+The fixtures are composed from the layout this library defines for the opcode,
+so they rule out a slip rather than a shared misreading. Payload bytes are all
+distinct from their neighbours, so a payload read from the wrong offset shows.
+'''
+
+import asyncio, os, struct, sys, logging
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+logging.disable(logging.CRITICAL)
+import mx_remote
+from mx_remote import DeviceFeature, MxrDeviceUid, ThirdPartyVendor
+from mx_remote.proto.Constants import THIRD_PARTY_PAYLOAD_MAX, ThirdPartyVendorFlag
+from mx_remote.proto.Factory import create_mxr_frame
+
+ADDR = ('192.0.2.9', 8812)
+OURS = bytes(range(0x20, 0x30))
+
+class Listening(mx_remote.MxrCallbacks):
+    def __init__(self):
+        self.messages = []
+    def on_third_party_message(self, dev, message):
+        self.messages.append((dev, message))
+
+seen = Listening()
+mx = mx_remote.Remote(open_connection=False, callbacks=seen)
+mx._uid = OURS
+sent = []
+mx.transmit = lambda data: (sent.append(bytes(data)), len(data))[1]
+
+def uid(n):
+    return bytes([n]) * 16
+
+def nm(s, sz=16):
+    b = s.encode('ascii')[:sz]
+    return b + bytes(sz - len(b))
+
+def body(n):
+    return bytes((0x80 + i * 7) & 0xFF for i in range(n))
+
+def rx(sender, payload, protocol=0x01):
+    '''A message stamped as a client stamps it, at the opcode's row.'''
+    frame = bytearray(create_mxr_frame(sender, 0x55, payload))
+    frame[2] = protocol
+    mx.process_frame(0.0, bytes(frame), ADDR)
+
+def known(n):
+    '''Another client, announced.'''
+    frame = bytearray(create_mxr_frame(uid(n), 0x00, struct.pack('<H', 0x30) + nm('audio-cast') + nm('P9SN00000000')
+                                       + nm('1.0.0') + struct.pack('<I', int(DeviceFeature.MANAGER))))
+    mx.process_frame(0.0, bytes(frame), ADDR)
+    seen.messages.clear()
+    return mx.get_by_uid(MxrDeviceUid(uid(n)))
+
+def call(coro):
+    return asyncio.run(coro)
+
+# ------------------------------------------------------------------- sending
+# Every device gets it at the lowest stamp, with the flag byte, the three
+# identifying bytes and the payload as given. A flag bit without a name goes
+# out as it was set.
+odk = ThirdPartyVendor(flags=ThirdPartyVendorFlag.NOT_OUI | ThirdPartyVendorFlag(0x40), id=b'ODK')
+sent.clear()
+assert call(mx.send_third_party(odk, body(41))) is True
+frame = sent[-1]
+assert frame[20:22] == bytes([0x55, 0x00]), frame[:24].hex()
+assert frame[2] == 0x01, f'stamped {frame[2]:#04x}'
+assert frame[24:28] == bytes([0x41]) + b'ODK', frame[24:28].hex()
+assert frame[28:] == body(41)
+print('send        : stamped 0x01, the vendor id then the payload as given')
+
+sent.clear()
+assert call(mx.send_third_party(ThirdPartyVendor.oui(bytes([0, 0x1A, 0x2B])), b'')) is True
+assert sent[-1][24:] == bytes([0, 0, 0x1A, 0x2B]), sent[-1][24:].hex()
+
+sent.clear()
+assert call(mx.send_third_party(odk, bytes(THIRD_PARTY_PAYLOAD_MAX))) is True, 'the largest payload was refused'
+assert len(sent[-1]) + 28 == 1500, 'the largest frame does not fill the MTU'
+
+sent.clear()
+assert call(mx.send_third_party(odk, bytes(THIRD_PARTY_PAYLOAD_MAX + 1))) is False
+assert not sent, 'an oversized message was sent'
+print('size        : an empty payload goes, and up to', THIRD_PARTY_PAYLOAD_MAX, 'bytes, which fill the MTU')
+
+# ------------------------------------------------------------------- receiving
+# The flag byte comes first and the three identifying bytes follow, and the
+# payload after them arrives byte for byte.
+dev = known(0x31)
+rx(uid(0x31), bytes([0x81]) + b'ODK' + body(37))
+assert len(seen.messages) == 1, seen.messages
+by, message = seen.messages[0]
+assert by is dev, by
+assert message.vendor.flags == ThirdPartyVendorFlag(0x81), message.vendor.flags
+assert message.vendor.id == b'ODK'
+assert message.payload == body(37)
+assert message.address == ADDR[0]
+assert message.vendor.same_vendor(ThirdPartyVendor.private(b'ODK'))
+print('receive     :', message)
+
+# A vendor id alone is a message with nothing after it, and anything shorter
+# is not a message.
+known(0x32)
+rx(uid(0x32), bytes([0x00, 0x00, 0x1A, 0x2B]))
+assert len(seen.messages) == 1, seen.messages
+assert seen.messages[0][1].vendor == ThirdPartyVendor.oui(bytes([0x00, 0x1A, 0x2B]))
+assert seen.messages[0][1].payload == b''
+seen.messages.clear()
+for n in range(4):
+    rx(uid(0x32), body(n))
+assert not seen.messages, seen.messages
+print('minimum     : the vendor id is the whole minimum')
+
+# A sender that has not announced itself is not heard.
+rx(uid(0x34), bytes([1]) + b'ODK' + bytes([7]))
+assert not seen.messages, seen.messages
+
+# This client never hears itself. Its own uid is never a known device either,
+# so the stranger rule drops the frame too, and only the two together being
+# lost turns this red.
+rx(OURS, bytes([1]) + b'ODK' + bytes([7]))
+assert not seen.messages, seen.messages
+print('senders     : a stranger and this client are not heard')
+
+# ------------------------------------------------------------------- vendors
+# Whether two ids name the same vendor rests on the not-an-OUI flag and the
+# three bytes, not on the other flag bits.
+plain = ThirdPartyVendor.private(b'ODK')
+assert plain.same_vendor(ThirdPartyVendor(flags=ThirdPartyVendorFlag(0xF1), id=b'ODK'))
+assert not plain.same_vendor(ThirdPartyVendor.oui(b'ODK'))
+for other in (b'ODL', b'PDK', b'OEK'):
+    assert not plain.same_vendor(ThirdPartyVendor.private(other)), other
+for wrong in (b'', b'OD', b'ODKX'):
+    try:
+        ThirdPartyVendor.private(wrong)
+    except ValueError:
+        continue
+    raise AssertionError(f'a {len(wrong)}-byte vendor id was taken')
+print('vendors     : the flag and the three bytes name a vendor')
+
+print('ALL OK')