mx-remote 4.7.9__tar.gz → 5.1.0__tar.gz

{mx_remote-4.7.9 → mx_remote-5.1.0}/CLAUDE.md

@@ -21,10 +21,57 @@ mxr                            # console app: discover devices, log frames live
 mxr -l <local_ip>              # bind to a specific interface
 mxr -b                         # broadcast mode instead of multicast
 mxr -i <capture> [-f <ip>]     # parse a MatrixOS/Wireshark capture file offline
+python tests/run.py            # run every protocol test
+python tests/run.py e2e stats  # run named suites only
 ```
 
-There is **no test suite** and no lint config in this repo. Validate protocol changes by
-running `mxr` against live hardware or by replaying a capture file with `mxr -i`.
+There is no lint config in this repo.
+
+`tests/` holds standalone scripts with no test framework behind it — each builds
+frames, feeds them through `Remote.process_frame`, and asserts what was decoded.
+A suite prints what it decoded and ends with `ALL OK`, so it can be run on its
+own as well as through `run.py`.
+
+Two things they pin that code review does not catch:
+
+- **Struct sizes, not just field offsets.** The V2IP stats blocks are 20 and 44
+  bytes only because the firmware's `ALIGN(8)` sits where GCC ignores it. Writing
+  that declaration the other way round shifts every block after the first, and a
+  wrong split still totals 128.
+- **Field widths.** Padding in the fixtures is filled with recognisable bytes, so
+  a field read at the right offset with the wrong width returns a wrong value. A
+  zero-filled fixture cannot catch that: the widened read returns the same
+  answer.
+- **Which handlers run at all.** `tests/handlers.py` reports how many frame
+  `process()` methods the other suites execute and fails if one loses its
+  coverage. A handler nothing calls is invisible to every other check here,
+  since they all measure tests that run.
+
+`tests/capture.py` holds real frames off a live mesh, with the device uids
+replaced. Its expected values come from firmware behaviour rather than from this
+decoder, which is the property a synthetic fixture cannot have — assert against
+something external, or a fixture only proves the decoder agrees with itself.
+
+Two things a test of a *command* must do, both of which look like coverage
+when they are missing:
+
+- **Assert both directions.** A command that returns False for an unrelated
+  reason satisfies a failure-only assertion on its own, so the success case is
+  what gives the failure case meaning.
+- **Pick an input that can reach the send.** Every multiviewer getter reads
+  `UNKNOWN` until a config frame arrives, and each setter returns True without
+  transmitting when the value already matches — so a table built from the first
+  enum member, which is `UNKNOWN`, never transmits at all.
+
+`tests/txresult.py` is the worked example of both.
+
+Validate wire changes against live hardware as well, by running `mxr` or
+replaying a capture file with `mxr -i`.
+
+A client's uid is persisted at `~/.mxr-uid`, one file per account, and
+`process_frame` drops any frame carrying our own uid. Two clients run from one
+account are a single identity to the mesh and each discards everything the other
+sends, so a second one needs its own `uid_path`.
 
 ### Versioning
 Version is single-sourced in `mx_remote/const.py` (`VERSION = '...'`); `pyproject.toml`
@@ -67,8 +114,17 @@ Three layers, decoupled by abstract base classes:
 `remote_id == self.uid` (our own echoes) are skipped.
 
 ### Frame wire format
-`[0x50, 0x38, protocol, 0x00]` ("P8" magic + protocol version) + opcode (u16 LE) +
-length (u16 LE) + payload. Built by `proto/Factory.py::create_mxr_frame`.
+A 24-byte header, then the payload:
+
+```
+0   [0x50, 0x38, protocol, 0x00]   "P8" magic + protocol version
+4   sender uid                     16 bytes, the device that sent this frame
+20  opcode                         u16 LE
+22  payload length                 u16 LE
+24  payload
+```
+
+Built by `proto/Factory.py::create_mxr_frame`, decoded by `proto/FrameHeader.py`.
 
 ## Working on the protocol
 

{mx_remote-4.7.9 → mx_remote-5.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mx_remote
-Version: 4.7.9
+Version: 5.1.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://github.com/opdenkamp/mx-remote/
@@ -30,14 +30,39 @@ Requires-Dist: aiohttp>=3.10.5
 Requires-Dist: netifaces>=0.11.0
 Description-Content-Type: text/markdown
 
-# MX Remote Interface
+# MX Remote — Pulse-Eight device interface
 
-Python 3 library for interfacing with [MX Remote](https://github.com/opdenkamp/mx-remote/) compatible devices over a local network. Supports device discovery, video/audio routing, volume control, remote control key passthrough, V2IP (OneIP) streaming, and more.
+Python 3 library for discovering and controlling [Pulse-Eight](https://www.pulse-eight.com/)
+AV distribution hardware over a local network: video/audio matrices, HDMI-over-IP
+encoders/decoders, multiviewers, and audio amplifiers. Supports device discovery,
+video/audio routing, volume control, remote-control key passthrough, HDMI-over-IP
+streaming, multiviewer control, and more.
+
+If you are looking to integrate Pulse-Eight **neo**, **OneIP**, or **ProAmp8** devices into
+your own software or home-automation system, this is the library for it.
+
+## What is MX Remote?
+
+MX Remote is the network protocol these Pulse-Eight devices use to discover and control one
+another over UDP (multicast or broadcast). All of them run the shared **MatrixOS** firmware,
+which speaks this protocol natively. This library is a client implementation of that
+protocol — its purpose is to expose the devices to third-party software.
+
+## Supported devices
+
+All devices below run MatrixOS and are controlled through the same protocol:
+
+- **[Pulse-Eight neo](https://www.pulse-eight.com/)** — HDBaseT video/audio matrices
+  (neo:4, neo:8, neo:X, and splitters)
+- **[Pulse-Eight OneIP](https://www.pulse-eight.com/p/248/oneip-tx)** — HDMI-over-IP
+  units: Transmitter (TX), Receiver (RX), Transceiver (TZ), and Multiviewer
+- **[Pulse-Eight ProAmp8](https://www.pulse-eight.com/p/219/proamp-8)** — 8-zone audio amplifier with
+  Dolby support
 
 ## Requirements
 
 - Python 3.11 or later
-- Network access to MX Remote compatible devices (multicast or broadcast)
+- Network access to one or more of the Pulse-Eight devices above (multicast or broadcast)
 
 ## Installation
 
@@ -91,11 +116,19 @@ mx = mx_remote.Remote(target_ip="10.8.8.255", port=8811)
 
 # offline mode for processing capture files
 mx = mx_remote.Remote(open_connection=False)
+
+# separate identity, to run concurrent clients from one account
+mx = mx_remote.Remote(uid_path="/var/lib/myapp/.mxr-uid")
 ```
 
+The uid at `uid_path` (default `~/.mxr-uid`) is this client's identity on the mesh:
+addressing is by uid in the payload, and a frame carrying our own uid is dropped as
+an echo. Two clients sharing a uid are one peer to every device and each silently
+discards everything the other sends, so give concurrent clients separate paths.
+
 ### Device
 
-A `DeviceBase` represents a physical device on the network (matrix, OneIP unit, amplifier). Devices are automatically registered when they respond to discovery requests.
+A `DeviceBase` represents a physical device on the network (a Pulse-Eight neo matrix, OneIP unit, or ProAmp8 amplifier). Devices are automatically registered when they respond to discovery requests.
 
 ```python
 # look up a device by serial number or unique ID
@@ -111,17 +144,23 @@ device.version         # firmware version
 device.online          # True if responding
 device.status          # DeviceStatus enum (ONLINE, OFFLINE, REBOOTING, BOOTING, INACTIVE)
 device.features        # DeviceFeatures bitmask
+device.config_initialised  # False if the device broadcasts config blocks built from
+                           # uninitialised memory; scaling, bay 0 addresses and the
+                           # rc target padding are unreliable from it
 device.temperatures    # dict of temperature sensor readings
 
 # device type checks
-device.is_v2ip             # OneIP device
-device.is_video_matrix     # video matrix
+device.is_v2ip             # Pulse-Eight OneIP HDMI-over-IP device
+device.is_video_matrix     # neo video matrix
 device.is_audio_matrix     # audio-only matrix
-device.is_amp              # audio amplifier
+device.is_amp              # ProAmp8 audio amplifier
 device.is_oneip_tx         # OneIP transmitter
 device.is_oneip_rx         # OneIP receiver
 device.is_oneip_tz         # OneIP transceiver
 device.is_oneip_multiviewer # OneIP multiviewer
+device.supports_video_wall  # sink can crop its source to a video wall window
+                            # (advertised ~1s after boot by the v2ipwall module,
+                            #  and never withdrawn once advertised)
 
 # iterate bays
 for port, bay in device.bays.items():
@@ -336,24 +375,28 @@ log = await device.get_log()
 result = await device.get_api("system/status")
 ```
 
-## OneIP (V2IP) Devices
+## Pulse-Eight OneIP Devices
 
-OneIP devices expose additional streaming properties:
+[Pulse-Eight OneIP](https://www.pulse-eight.com/p/248/oneip-tx) HDMI-over-IP devices expose additional streaming properties:
 
 ```python
-# V2IP stream source addresses
+# 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}")
 
-# V2IP device details (encoder/decoder config)
+# 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}")
+    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
 
-# V2IP statistics
+# streaming statistics
 await device.read_stats(enable=True)   # start collecting
 # ... later ...
 stats = device.v2ip_stats
@@ -368,9 +411,9 @@ if device.v2ip_firmware_versions:
         print(f"{fw_type}: {fw.version}")
 ```
 
-## OneIP Multiviewer
+## Pulse-Eight OneIP Multiviewer
 
-Control multiviewer-specific settings:
+Control [OneIP Multiviewer](https://www.pulse-eight.com/p/248/oneip-tx)-specific settings:
 
 ```python
 from mx_remote import (

{mx_remote-4.7.9 → mx_remote-5.1.0}/README.md

@@ -1,11 +1,36 @@
-# MX Remote Interface
+# MX Remote — Pulse-Eight device interface
 
-Python 3 library for interfacing with [MX Remote](https://github.com/opdenkamp/mx-remote/) compatible devices over a local network. Supports device discovery, video/audio routing, volume control, remote control key passthrough, V2IP (OneIP) streaming, and more.
+Python 3 library for discovering and controlling [Pulse-Eight](https://www.pulse-eight.com/)
+AV distribution hardware over a local network: video/audio matrices, HDMI-over-IP
+encoders/decoders, multiviewers, and audio amplifiers. Supports device discovery,
+video/audio routing, volume control, remote-control key passthrough, HDMI-over-IP
+streaming, multiviewer control, and more.
+
+If you are looking to integrate Pulse-Eight **neo**, **OneIP**, or **ProAmp8** devices into
+your own software or home-automation system, this is the library for it.
+
+## What is MX Remote?
+
+MX Remote is the network protocol these Pulse-Eight devices use to discover and control one
+another over UDP (multicast or broadcast). All of them run the shared **MatrixOS** firmware,
+which speaks this protocol natively. This library is a client implementation of that
+protocol — its purpose is to expose the devices to third-party software.
+
+## Supported devices
+
+All devices below run MatrixOS and are controlled through the same protocol:
+
+- **[Pulse-Eight neo](https://www.pulse-eight.com/)** — HDBaseT video/audio matrices
+  (neo:4, neo:8, neo:X, and splitters)
+- **[Pulse-Eight OneIP](https://www.pulse-eight.com/p/248/oneip-tx)** — HDMI-over-IP
+  units: Transmitter (TX), Receiver (RX), Transceiver (TZ), and Multiviewer
+- **[Pulse-Eight ProAmp8](https://www.pulse-eight.com/p/219/proamp-8)** — 8-zone audio amplifier with
+  Dolby support
 
 ## Requirements
 
 - Python 3.11 or later
-- Network access to MX Remote compatible devices (multicast or broadcast)
+- Network access to one or more of the Pulse-Eight devices above (multicast or broadcast)
 
 ## Installation
 
@@ -59,11 +84,19 @@ mx = mx_remote.Remote(target_ip="10.8.8.255", port=8811)
 
 # offline mode for processing capture files
 mx = mx_remote.Remote(open_connection=False)
+
+# separate identity, to run concurrent clients from one account
+mx = mx_remote.Remote(uid_path="/var/lib/myapp/.mxr-uid")
 ```
 
+The uid at `uid_path` (default `~/.mxr-uid`) is this client's identity on the mesh:
+addressing is by uid in the payload, and a frame carrying our own uid is dropped as
+an echo. Two clients sharing a uid are one peer to every device and each silently
+discards everything the other sends, so give concurrent clients separate paths.
+
 ### Device
 
-A `DeviceBase` represents a physical device on the network (matrix, OneIP unit, amplifier). Devices are automatically registered when they respond to discovery requests.
+A `DeviceBase` represents a physical device on the network (a Pulse-Eight neo matrix, OneIP unit, or ProAmp8 amplifier). Devices are automatically registered when they respond to discovery requests.
 
 ```python
 # look up a device by serial number or unique ID
@@ -79,17 +112,23 @@ device.version         # firmware version
 device.online          # True if responding
 device.status          # DeviceStatus enum (ONLINE, OFFLINE, REBOOTING, BOOTING, INACTIVE)
 device.features        # DeviceFeatures bitmask
+device.config_initialised  # False if the device broadcasts config blocks built from
+                           # uninitialised memory; scaling, bay 0 addresses and the
+                           # rc target padding are unreliable from it
 device.temperatures    # dict of temperature sensor readings
 
 # device type checks
-device.is_v2ip             # OneIP device
-device.is_video_matrix     # video matrix
+device.is_v2ip             # Pulse-Eight OneIP HDMI-over-IP device
+device.is_video_matrix     # neo video matrix
 device.is_audio_matrix     # audio-only matrix
-device.is_amp              # audio amplifier
+device.is_amp              # ProAmp8 audio amplifier
 device.is_oneip_tx         # OneIP transmitter
 device.is_oneip_rx         # OneIP receiver
 device.is_oneip_tz         # OneIP transceiver
 device.is_oneip_multiviewer # OneIP multiviewer
+device.supports_video_wall  # sink can crop its source to a video wall window
+                            # (advertised ~1s after boot by the v2ipwall module,
+                            #  and never withdrawn once advertised)
 
 # iterate bays
 for port, bay in device.bays.items():
@@ -304,24 +343,28 @@ log = await device.get_log()
 result = await device.get_api("system/status")
 ```
 
-## OneIP (V2IP) Devices
+## Pulse-Eight OneIP Devices
 
-OneIP devices expose additional streaming properties:
+[Pulse-Eight OneIP](https://www.pulse-eight.com/p/248/oneip-tx) HDMI-over-IP devices expose additional streaming properties:
 
 ```python
-# V2IP stream source addresses
+# 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}")
 
-# V2IP device details (encoder/decoder config)
+# 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}")
+    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
 
-# V2IP statistics
+# streaming statistics
 await device.read_stats(enable=True)   # start collecting
 # ... later ...
 stats = device.v2ip_stats
@@ -336,9 +379,9 @@ if device.v2ip_firmware_versions:
         print(f"{fw_type}: {fw.version}")
 ```
 
-## OneIP Multiviewer
+## Pulse-Eight OneIP Multiviewer
 
-Control multiviewer-specific settings:
+Control [OneIP Multiviewer](https://www.pulse-eight.com/p/248/oneip-tx)-specific settings:
 
 ```python
 from mx_remote import (