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

{mx_remote-5.5.0 → mx_remote-5.6.0}/.gitignore

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

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

@@ -73,6 +73,13 @@ A client's uid is persisted at `~/.mxr-uid`, one file per account, and
 account are a single identity to the mesh and each discards everything the other
 sends, so a second one needs its own `uid_path`.
 
+### Python versions
+`requires-python` is 3.11, and `.github/workflows/tests.yml` runs the suites on
+3.11, 3.12 and 3.13 so that floor is checked rather than assumed. A name that
+only exists on a newer version goes through `mx_remote/compat.py`, the one place
+that tests `sys.version_info`, and its fallback needs a dependency marked
+`python_version < '<the version that added it>'` in `pyproject.toml`.
+
 ### Versioning
 Version is single-sourced in `mx_remote/const.py` (`VERSION = '...'`); `pyproject.toml`
 reads it via regex, so bump it there only. Release commits follow the convention

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mx_remote
-Version: 5.5.0
+Version: 5.6.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/
@@ -28,6 +28,7 @@ Requires-Python: >=3.11
 Requires-Dist: aiofiles>=24.1.0
 Requires-Dist: aiohttp>=3.10.5
 Requires-Dist: netifaces>=0.11.0
+Requires-Dist: typing-extensions>=4.4; python_version < '3.12'
 Description-Content-Type: text/markdown
 
 # MX Remote - Python Client for Pulse-Eight MatrixOS devices

mx_remote-5.6.0/docs/oneip.md

@@ -0,0 +1,109 @@
+# 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)
+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.
+
+## 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.6.0/mx_remote/compat.py

@@ -0,0 +1,22 @@
+######################################################
+##            MX Remote Python Interface            ##
+##                                                  ##
+## author: Lars Op den Kamp (lars@opdenkamp-it.nl)  ##
+## copyright (c) 2021-2026 Op den Kamp IT Solutions ##
+######################################################
+
+"""
+Names that live in different modules across the Python versions this package
+supports. Import them from here so the version test is written once.
+"""
+
+import sys
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    # typing.override arrived in 3.12; typing_extensions carries the same
+    # decorator further back, and is a dependency only below that version.
+    from typing_extensions import override
+
+__all__ = ['override']

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

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

{mx_remote-5.5.0 → mx_remote-5.6.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

{mx_remote-5.5.0 → mx_remote-5.6.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.0 → mx_remote-5.6.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)

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/FrameSystemStatus.py

@@ -6,7 +6,7 @@
 ######################################################
 '''Protocol frame for device system status notifications.'''
 
-from typing import override
+from ..compat import override
 from .FrameBase import FrameBase
 
 class FrameSystemStatus(FrameBase):

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/FrameSystemStatus.pyi

@@ -1,5 +1,5 @@
+from ..compat import override as override
 from .FrameBase import FrameBase as FrameBase
-from typing import override
 
 class FrameSystemStatus(FrameBase):
     @override

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/FrameV2IPAudio.py

@@ -10,7 +10,7 @@ from enum import IntEnum
 from functools import cached_property
 import logging
 import struct
-from typing import override
+from ..compat import override
 
 from .FrameHeader import FrameHeader
 from .FrameBase import FrameBase
@@ -434,15 +434,21 @@ class AudioConfig:
 # SELECT_INPUT payload, as construct() below writes it:
 #   0..2     u16 sub-opcode
 #   2..4     padding
-#   4..20    target uid    (the sink; _audio_cmd_header always puts the target here)
-#   20..36   target uid    again
+#   4..20    device uid    (the hop this frame is addressed to)
+#   20..36   target uid    (the sink, whose endpoint changes source)
 #   36..52   source uid
 #   52..54   u16 target endpoint id
 #   54..56   u16 source endpoint id
 #
-# The uid at 4 and the uid at 20 are the same device: the sink is the frame's
-# target. That is what settles the orientation - reading 20 as the source would
-# make one uid both the target and the source of a single frame.
+# Read the route from the body alone. The uid at 4 names whichever device is
+# addressed for the hop that carried this frame, which is the sink only when the
+# route has one hop - so taking the sink from there mislabels every longer
+# route, even though a single-hop command puts the same uid in both.
+#
+# The firmware struct calls the body's first uid the source and its second the
+# target, the reverse of what they hold, so the field names cannot settle the
+# orientation either. Nothing on the wire tells a swapped reading from a correct
+# one; the test vector is what holds it.
 
 class AudioChangeSourceImpl(AudioChangeSource):
     '''Parsed audio source change request with source and target identifiers.'''
@@ -456,7 +462,7 @@ class AudioChangeSourceImpl(AudioChangeSource):
 
     @property
     def target_uid(self) -> MxrDeviceUid|None:
-        '''Device whose endpoint is changing source - the frame's target.'''
+        '''Device whose endpoint is changing source, read from the body.'''
         return self.data.payload_uuid(idx=20)
 
     @property

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/FrameV2IPAudio.pyi

@@ -1,10 +1,10 @@
 from ..Interface import AudioChangeSource as AudioChangeSource, AudioEndpoint as AudioEndpoint, AudioEndpoints as AudioEndpoints, AudioFeatures as AudioFeatures, AudioLink as AudioLink, AudioLinks as AudioLinks, DeviceRegistry as DeviceRegistry, MxrDeviceUid as MxrDeviceUid, V2IPStreamSource as V2IPStreamSource
+from ..compat import override as override
 from .FrameBase import FrameBase as FrameBase
 from .FrameHeader import FrameHeader as FrameHeader
 from _typeshed import Incomplete
 from enum import IntEnum
 from functools import cached_property
-from typing import override
 
 V2IP_AUDIO_EP_ID_NONE: int
 

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/FrameV2IPBayMapping.py

@@ -7,7 +7,7 @@
 '''Protocol frame for V2IP bay-to-device UID mapping.'''
 
 from functools import cached_property
-from typing import override
+from ..compat import override
 from ..Interface import MxrDeviceUid
 from .FrameBase import FrameBase
 

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/FrameV2IPBayMapping.pyi

@@ -1,7 +1,7 @@
 from ..Interface import MxrDeviceUid as MxrDeviceUid
+from ..compat import override as override
 from .FrameBase import FrameBase as FrameBase
 from functools import cached_property
-from typing import override
 
 class FrameV2IPBayMapping(FrameBase):
     @cached_property

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/FrameV2IPMultiviewer.py

@@ -8,7 +8,7 @@
 
 from enum import Enum
 from functools import cached_property
-from typing import override
+from ..compat import override
 from .FrameBase import FrameBase
 from .Constants import decode_enum
 from ..Interface import MxrDeviceUid, DeviceBase, DeviceRegistry

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/FrameV2IPMultiviewer.pyi

@@ -1,10 +1,10 @@
 from .Multiviewer import *
 from ..Interface import DeviceBase as DeviceBase, DeviceRegistry as DeviceRegistry, MxrDeviceUid as MxrDeviceUid
+from ..compat import override as override
 from .Constants import decode_enum as decode_enum
 from .FrameBase import FrameBase as FrameBase
 from enum import Enum as Enum
 from functools import cached_property
-from typing import override
 
 class V2IPMultiviewerConfig(FrameBase, MultiviewerConfig):
     @property

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/FrameV2IPStats.py

@@ -9,22 +9,46 @@
 from functools import cached_property
 import warnings
 from .FrameBase import FrameBase
-from .V2IPStats import V2IPRxStats, V2IPTxStats, V2IPDeviceStats
+from .V2IPStats import (V2IPRxStats, V2IPTxStats, V2IPDeviceStats, V2IPDecoderDetail,
+    V2IP_DECODER_DETAIL_OFFSET, V2IP_DECODER_PROTOCOL, V2IP_STATS_COUNTERS_LEN,
+    V2IP_STATS_FULL_LEN)
 from ..Interface import DeviceBase, DeviceRegistry
 
 class FrameV2IPStats(FrameBase):
     '''V2IP encoder/decoder statistics report.'''
     @staticmethod
     def construct(registry:DeviceRegistry, device:DeviceBase, enable:bool) -> FrameBase|None:
-        '''Build a stats enable/disable request frame for transmission.'''
+        '''Build a stats enable/disable request frame for transmission.
+
+        There is no free-running mode: a device reports only while a
+        subscription is live, and the subscription lapses 60s after this frame.
+        Send it again inside the minute to keep the 1Hz reports coming.
+
+        The 17-byte form is the only one a device acts on; any other length is
+        ignored.'''
         payload = device.remote_id.byte_value
         payload += bytes([1]) if enable else bytes([0])
         return FrameBase.construct_base(mxr=registry, opcode=0x3F, payload=payload)
 
     @cached_property
     def is_request(self) -> bool:
+        '''Whether this is the enable/disable request, which carries no counters.'''
         return (self.payload is not None) and (len(self.payload) == 17)
 
+    @cached_property
+    def is_report(self) -> bool:
+        '''Whether the payload is long enough to hold the counter blocks.
+
+        The length is the only thing separating the two forms this opcode
+        carries: a request is a uid and a flag, far short of the counters.
+
+        Everything between the two forms is a truncated report, and reading one
+        raises: payload_idx clamps a slice to what arrived rather than failing,
+        so each block below is handed a buffer too short and refuses it. That
+        reaches str(self) as readily as process(), and the receive path renders
+        every frame it decodes to its debug log before processing it.'''
+        return (self.payload is not None) and (len(self.payload) >= V2IP_STATS_COUNTERS_LEN)
+
     @cached_property
     def stats_enabled(self) -> bool:
         pl = self.payload_bool(16)
@@ -60,6 +84,27 @@ class FrameV2IPStats(FrameBase):
             raise Exception("invalid FrameV2IPStats size")
         return V2IPRxStats(pl)
 
+    @cached_property
+    def decoder(self) -> V2IPDecoderDetail|None:
+        '''What the sink's decoder recovered, None from a sender that predates it.
+
+        Recognised by the frame's stamp and its length together. The length
+        says the payload is long enough to hold the block; the stamp says those
+        bytes are that block rather than some later growth this client has no
+        name for. A sender below V2IP_DECODER_PROTOCOL appended no such block,
+        so reading its tail would invent a reason, a geometry and a fault word.
+        Its counters are still read.
+
+        Neither answers whether a reserved field has been spent: a firmware that
+        gives the block's reserved byte a meaning still stamps this version and
+        still sends 152 bytes.'''
+        if (self.protocol < V2IP_DECODER_PROTOCOL):
+            return None
+        pl = self.payload_idx(start=V2IP_DECODER_DETAIL_OFFSET, end=V2IP_STATS_FULL_LEN)
+        if (pl is None) or (len(pl) < (V2IP_STATS_FULL_LEN - V2IP_DECODER_DETAIL_OFFSET)):
+            return None
+        return V2IPDecoderDetail(pl)
+
     @cached_property
     def stats(self) -> V2IPDeviceStats:
         rv = V2IPDeviceStats()
@@ -67,14 +112,17 @@ class FrameV2IPStats(FrameBase):
         rv.tx_per_minute = self.tx_per_minute
         rv.rx = self.rx
         rv.rx_per_minute = self.rx_per_minute
+        rv.decoder = self.decoder
         return rv
 
     def process(self) -> None:
         '''Update the local device cache with V2IP statistics.'''
-        if (not self.is_request) and ((dev := self.remote_device) is not None):
+        if self.is_report and ((dev := self.remote_device) is not None):
             dev.on_mxr_update(self.stats)
 
     def __str__(self) -> str:
         if self.is_request:
             return f"{str(self.remote_device)} v2ip stats request: {self.stats_enabled}"
+        if not self.is_report:
+            return f"{str(self.remote_device)} v2ip stats: {len(self)} bytes, too short to read"
         return f"{str(self.remote_device)} v2ip stats: {self.stats}"

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/FrameV2IPStats.pyi

@@ -1,6 +1,6 @@
 from ..Interface import DeviceBase as DeviceBase, DeviceRegistry as DeviceRegistry
 from .FrameBase import FrameBase as FrameBase
-from .V2IPStats import V2IPDeviceStats as V2IPDeviceStats, V2IPRxStats as V2IPRxStats, V2IPTxStats as V2IPTxStats
+from .V2IPStats import V2IPDecoderDetail as V2IPDecoderDetail, V2IPDeviceStats as V2IPDeviceStats, V2IPRxStats as V2IPRxStats, V2IPTxStats as V2IPTxStats, V2IP_DECODER_DETAIL_OFFSET as V2IP_DECODER_DETAIL_OFFSET, V2IP_DECODER_PROTOCOL as V2IP_DECODER_PROTOCOL, V2IP_STATS_COUNTERS_LEN as V2IP_STATS_COUNTERS_LEN, V2IP_STATS_FULL_LEN as V2IP_STATS_FULL_LEN
 from functools import cached_property
 
 class FrameV2IPStats(FrameBase):
@@ -9,6 +9,8 @@ class FrameV2IPStats(FrameBase):
     @cached_property
     def is_request(self) -> bool: ...
     @cached_property
+    def is_report(self) -> bool: ...
+    @cached_property
     def stats_enabled(self) -> bool: ...
     @cached_property
     def tx(self) -> V2IPTxStats: ...
@@ -19,5 +21,7 @@ class FrameV2IPStats(FrameBase):
     @cached_property
     def rx_per_minute(self) -> V2IPRxStats: ...
     @cached_property
+    def decoder(self) -> V2IPDecoderDetail | None: ...
+    @cached_property
     def stats(self) -> V2IPDeviceStats: ...
     def process(self) -> None: ...

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/V2IPConfig.py

@@ -6,7 +6,8 @@
 ######################################################
 '''Video-over-IP stream source configuration and parsing.'''
 
-from typing import Any, override
+from typing import Any
+from ..compat import override
 from ..Uid import MxrDeviceUid
 from ..Interface import V2IPStreamSource, V2IPStreamSources, V2IPAudioFormat
 import socket

{mx_remote-5.5.0 → mx_remote-5.6.0}/mx_remote/proto/V2IPConfig.pyi

@@ -1,7 +1,8 @@
 from ..Interface import V2IPAudioFormat as V2IPAudioFormat, V2IPStreamSource as V2IPStreamSource, V2IPStreamSources as V2IPStreamSources
 from ..Uid import MxrDeviceUid as MxrDeviceUid
+from ..compat import override as override
 from _typeshed import Incomplete
-from typing import Any, override
+from typing import Any
 
 class V2IPStreamSourceImpl(V2IPStreamSource):
     def __init__(self, label: str, data: bytes) -> None: ...