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

mx_remote-5.3.0/CLAUDE.md → mx_remote-5.5.0/AGENTS.md

@@ -1,6 +1,6 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for coding agents working in this repository.
 
 ## What this is
 
@@ -83,6 +83,21 @@ reads it via regex, so bump it there only. Release commits follow the convention
 force-includes them in the wheel (they are gitignored). `mx_remote` ships as typed
 (`py.typed`). If stubgen produces nothing the build fails by design.
 
+### Documentation
+`docs/` is both the GitHub-readable guide set and the Sphinx source for
+[the published site](https://opdenkamp.github.io/mx-remote/), which
+`.github/workflows/docs.yml` rebuilds on every push to master. Build it the way
+the workflow does:
+
+```sh
+pip install . -r docs/requirements.txt
+sphinx-build -b html -W --keep-going docs site
+```
+
+Autodoc emits reStructuredText, so a directive belongs in an ```` ```{eval-rst} ````
+block. Outside one it renders as its own source and the build still reports
+success — the workflow greps the output for that.
+
 ## Architecture
 
 Three layers, decoupled by abstract base classes:
@@ -105,7 +120,7 @@ Three layers, decoupled by abstract base classes:
    - `Device` (`DeviceBase`), `Bay` (`BayBase`) — live device/port state.
    - `ConnectionAsync` — `asyncio.DatagramProtocol` UDP transport (multicast/broadcast).
    - `State` — dispatches events to registered `MxrCallbacks`.
-   - `V2IP`, `Link`, `P8PDU` — OneIP streaming, virtual bay links, PDU support.
+   - `V2IP`, `Link` — OneIP streaming and virtual bay links.
 
 ### Receive data flow
 `ConnectionAsync` datagram → `Remote.on_datagram_received` → `Remote.process_frame` →
@@ -131,5 +146,78 @@ Built by `proto/Factory.py::create_mxr_frame`, decoded by `proto/FrameHeader.py`
 When adding or editing a `Frame*` class, byte layouts **must match the MatrixOS firmware C
 structs** — verify against the firmware source rather than inferring from samples. Adding a
 new opcode requires both the `Frame*` class and a dispatch entry in
-`Factory.py::_mxr_frame_factory`. Note the proto/ and remote/ modules use tab indentation
+`Factory.py::_mxr_frame_factory`.
+
+Get sizes and offsets from a compiler, not by adding up field widths. Two things
+defeat reading:
+
+- `mxr_uid` is `uint32_t[4]`, so it aligns to 4 and shifts every field behind it
+  in a struct that is not `PACKED`.
+- an `ALIGN(8)` struct is as wide as its alignment rounds it to, and its tail
+  padding is part of the payload. Receivers test `len < sizeof(...)` before
+  reading a field, so a frame short by its padding is dropped without a reply —
+  which looks exactly like one that was accepted and ignored.
+
+Paste the struct into a throwaway `.c` file with `__builtin_offsetof` and run it.
+Note that `uint_fast16_t` is 4 bytes on the target, so model it as `uint32_t`
+rather than letting the host pick.
+
+Compile the struct's *own* component types, at the version you are decoding.
+Substituting today's equivalents makes the result a reconstruction rather than a
+measurement, and a reconstruction that happens to be right is indistinguishable
+from one that is wrong until something else disagrees with it. Types get renamed
+and moved between headers without their layout changing, so a name that no
+longer exists is not evidence that the layout did change.
+
+`PACKED` on a struct sets where its members are *placed*, not how wide they are.
+A nested aggregate keeps its own internal padding, so a packed struct holding an
+array of unpacked 12-byte records still spends 48 bytes on four of them — it
+just starts them at an unaligned offset. Assuming the nesting flattens gives a
+smaller size that looks plausible and decodes.
+
+A protocol version outlives layout revisions. The struct at the commit that
+introduced a version is not necessarily the struct any device sent under it, and
+two revisions can share one version — so date a layout from the releases that
+carried it, not from the commit that named it.
+
+That needs both halves of the release history, which only the firmware side has.
+The tag says what bytes a version sends; the distribution list says whether
+anyone runs it. Tags alone invent field versions nobody has, and this protocol
+has several — versions tagged and never uploaded are why two apparent
+compatibility problems here turned out not to exist.
+
+The protocol floor in `MXR_OPCODE_VERSIONS` is a delivery gate, not a layout
+selector. A payload can widen without its floor moving, and then the stamp says
+nothing about which layout arrived — dispatch on payload length instead.
+`tests/wirefix.py` covers the cases where the two come apart.
+
+## Writing down a deliberate divergence
+
+A note recording *what the firmware does* reads as *what this library should
+do*, and the gap between them is where every deliberate difference lives. So
+write the divergence beside the fact, not somewhere else: "firmware ignores this
+below 0x22" invites the next reader to delete the path that decodes it, where
+"firmware ignores it, we decode it anyway, because those units still transmit
+and nothing else answers them" does not.
+
+This library is older than the firmware currently shipping and serves versions
+that will never be upgraded, so it decodes more than any device does. That is
+the intended relationship, not drift to be tidied up.
+
+## Fixtures that cannot fail
+
+A fixture can be too simple to reach the code under test. It can also be too
+*helpful*: it reaches the code with the interesting input already removed, or it
+supplies for free the precondition the code is supposed to establish. The second
+kind is worse, because it occupies the slot where the real test would go and
+reports green forever.
+
+Ask what the setup does for the code, and whether a caller gets that for free.
+A frame stamped at a version no device sends, a payload length chosen so that
+one wrong branch still parses, a send exercised only against a device that had
+already been introduced to us — each passes, and none of them can fail.
+
+The check is mechanical: break the thing the test is for, one part at a time,
+and watch that test go red for the right reason. An assertion that fires on a
+sanity check placed above the subject has tested nothing. Note the proto/ and remote/ modules use tab indentation
 while `Interface.py` and `const.py` use spaces — match the file you are editing.

mx_remote-5.5.0/CLAUDE.md

@@ -0,0 +1,4 @@
+# CLAUDE.md
+
+The instructions for this repository live in [AGENTS.md](AGENTS.md), in the
+format every agent reads. This file only points at them.

mx_remote-5.5.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: mx_remote
+Version: 5.5.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/
+Project-URL: Repository, https://github.com/opdenkamp/mx-remote.git
+Project-URL: Bug Tracker, https://github.com/opdenkamp/mx-remote/issues
+Author-email: Lars Op den Kamp <lars@opdenkamp-it.nl>
+Maintainer-email: Lars Op den Kamp <lars@opdenkamp-it.nl>
+License: Copyright 2021-2026 Lars Op den Kamp <lars@opdenkamp-it.nl>
+        
+        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: LICENSE
+Keywords: ampos,matrixos,oneip,pulse-eight
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.10.5
+Requires-Dist: netifaces>=0.11.0
+Description-Content-Type: text/markdown
+
+# MX Remote - Python Client for Pulse-Eight MatrixOS devices
+
+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.
+
+**Documentation:** [opdenkamp.github.io/mx-remote](https://opdenkamp.github.io/mx-remote/)
+
+## 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 one or more of the Pulse-Eight devices above (multicast or broadcast)
+
+## Installation
+
+```bash
+pip install .
+```
+
+## Quick Start
+
+The minimum code to discover devices on the network:
+
+```python
+import asyncio
+import mx_remote
+
+async def main():
+    mx = mx_remote.Remote()
+    await mx.start_async()
+
+    # wait for devices to be discovered
+    await asyncio.sleep(5)
+
+    for uid, device in mx.remotes.items():
+        print(f"{device.serial} ({device.name}) - {device.model_name} - {device.status}")
+        for port, bay in device.bays.items():
+            print(f"  {bay.bay_label} [{bay.mode}] signal={bay.signal_detected}")
+
+    await mx.close()
+
+asyncio.run(main())
+```
+
+## Documentation
+
+The guides below are published at
+**[opdenkamp.github.io/mx-remote](https://opdenkamp.github.io/mx-remote/)** alongside an
+API reference generated from the docstrings, and are readable here in
+[docs/](docs/README.md).
+
+| Page | Covers |
+| --- | --- |
+| [Configuration](docs/configuration.md) | Opening a connection and keeping it in step with the mesh. |
+| [Devices and bays](docs/devices-and-bays.md) | Naming, hiding, EDID and the device registry. |
+| [Routing](docs/routing.md) | Selecting video and audio sources for an output. |
+| [Callbacks](docs/callbacks.md) | Reacting to state changes rather than polling for them. |
+| [Audio](docs/audio.md) | Volume, mute and remote-control passthrough. |
+| [OneIP and V2IP](docs/oneip.md) | Streaming endpoints, stream sources and statistics. |
+| [Multiviewer](docs/multiviewer.md) | Layout, sources and output configuration. |
+| [Diagnostics](docs/diagnostics.md) | Network status, the mxr console app and capture replay. |
+
+## Other languages
+
+The same protocol, implemented independently:
+
+- **Go** — https://github.com/opdenkamp/mx-remote-golang
+- **Rust** — https://github.com/opdenkamp/mx-remote-rust (also ships a C ABI, for C and C++)
+
+Python is the oldest of the three and the one that still decodes what older
+firmware sent: `0x06`, `0x36` and `0x47` are superseded opcodes kept because a
+unit on older firmware still emits them. So it decodes a slightly wider set than
+the others, and the difference is deliberate rather than drift.
+
+## License
+
+BSD 3-Clause License. See [LICENSE](LICENSE) for details.
+

mx_remote-5.5.0/README.md

@@ -0,0 +1,101 @@
+# MX Remote - Python Client for Pulse-Eight MatrixOS devices
+
+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.
+
+**Documentation:** [opdenkamp.github.io/mx-remote](https://opdenkamp.github.io/mx-remote/)
+
+## 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 one or more of the Pulse-Eight devices above (multicast or broadcast)
+
+## Installation
+
+```bash
+pip install .
+```
+
+## Quick Start
+
+The minimum code to discover devices on the network:
+
+```python
+import asyncio
+import mx_remote
+
+async def main():
+    mx = mx_remote.Remote()
+    await mx.start_async()
+
+    # wait for devices to be discovered
+    await asyncio.sleep(5)
+
+    for uid, device in mx.remotes.items():
+        print(f"{device.serial} ({device.name}) - {device.model_name} - {device.status}")
+        for port, bay in device.bays.items():
+            print(f"  {bay.bay_label} [{bay.mode}] signal={bay.signal_detected}")
+
+    await mx.close()
+
+asyncio.run(main())
+```
+
+## Documentation
+
+The guides below are published at
+**[opdenkamp.github.io/mx-remote](https://opdenkamp.github.io/mx-remote/)** alongside an
+API reference generated from the docstrings, and are readable here in
+[docs/](docs/README.md).
+
+| Page | Covers |
+| --- | --- |
+| [Configuration](docs/configuration.md) | Opening a connection and keeping it in step with the mesh. |
+| [Devices and bays](docs/devices-and-bays.md) | Naming, hiding, EDID and the device registry. |
+| [Routing](docs/routing.md) | Selecting video and audio sources for an output. |
+| [Callbacks](docs/callbacks.md) | Reacting to state changes rather than polling for them. |
+| [Audio](docs/audio.md) | Volume, mute and remote-control passthrough. |
+| [OneIP and V2IP](docs/oneip.md) | Streaming endpoints, stream sources and statistics. |
+| [Multiviewer](docs/multiviewer.md) | Layout, sources and output configuration. |
+| [Diagnostics](docs/diagnostics.md) | Network status, the mxr console app and capture replay. |
+
+## Other languages
+
+The same protocol, implemented independently:
+
+- **Go** — https://github.com/opdenkamp/mx-remote-golang
+- **Rust** — https://github.com/opdenkamp/mx-remote-rust (also ships a C ABI, for C and C++)
+
+Python is the oldest of the three and the one that still decodes what older
+firmware sent: `0x06`, `0x36` and `0x47` are superseded opcodes kept because a
+unit on older firmware still emits them. So it decodes a slightly wider set than
+the others, and the difference is deliberate rather than drift.
+
+## License
+
+BSD 3-Clause License. See [LICENSE](LICENSE) for details.
+

mx_remote-5.5.0/docs/README.md

@@ -0,0 +1,14 @@
+# Documentation
+
+The API reference for `mx_remote`. Start at the [project README](https://github.com/opdenkamp/mx-remote#readme) for installation and a quick start.
+
+| Page | Covers |
+| --- | --- |
+| [Configuration](configuration.md) | Opening a connection and keeping it in step with the mesh. |
+| [Devices and bays](devices-and-bays.md) | Naming, hiding, EDID and the device registry. |
+| [Routing](routing.md) | Selecting video and audio sources for an output. |
+| [Callbacks](callbacks.md) | Reacting to state changes rather than polling for them. |
+| [Audio](audio.md) | Volume, mute and remote-control passthrough. |
+| [OneIP and V2IP](oneip.md) | Streaming endpoints, stream sources and statistics. |
+| [Multiviewer](multiviewer.md) | Layout, sources and output configuration. |
+| [Diagnostics](diagnostics.md) | Network status, the mxr console app and capture replay. |

mx_remote-5.5.0/docs/_static/brand.css

@@ -0,0 +1,34 @@
+/* Shapes Furo to the house style. The palette itself is set in conf.py, where
+   Furo wants it; this file holds what a variable cannot express. */
+
+/* The mark is portrait, so a width bound keeps it from filling the sidebar. */
+.sidebar-logo {
+  max-width: 4.5rem;
+  margin: 0 auto 0.5rem;
+}
+
+.sidebar-brand-text {
+  font-weight: 600;
+  letter-spacing: -0.025em;
+}
+
+h1, h2, h3, h4 {
+  letter-spacing: -0.025em;
+}
+
+/* Furo underlines links only on hover; the guides lean on them heavily enough
+   that a reader should see where they are while scanning. */
+article a.reference.internal,
+article a.reference.external {
+  text-decoration-color: var(--color-brand-content);
+  text-decoration-line: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 0.15em;
+}
+
+/* Signatures are the spine of the API reference: give them the brand rule so
+   they read as landmarks rather than as another grey block. */
+dl.py > dt {
+  border-left: 3px solid var(--color-brand-content);
+  padding-left: 0.6rem;
+}

mx_remote-5.5.0/docs/_static/favicon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="27 7 86 86" width="86" height="86" role="img" aria-label="Op den Kamp IT Solutions">
+  <circle cx="70" cy="50" r="30" fill="none" stroke="#0588c4" stroke-width="26"/>
+</svg>

mx_remote-5.5.0/docs/_static/logo-dark.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="20 0 120 190" width="120" height="190" role="img" aria-label="Op den Kamp IT Solutions">
+  <circle cx="70" cy="50" r="30" fill="none" stroke="#0588c4" stroke-width="26"/>
+  <g fill="#5aafc0">
+    <rect x="27" y="117" width="16" height="66"/>
+    <rect x="57" y="117" width="76" height="16"/>
+    <rect x="87" y="117" width="16" height="66"/>
+  </g>
+</svg>

mx_remote-5.5.0/docs/_static/logo.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="20 0 120 190" width="120" height="190" role="img" aria-label="Op den Kamp IT Solutions">
+  <circle cx="70" cy="50" r="30" fill="none" stroke="#0588c4" stroke-width="26"/>
+  <g fill="#117a8b">
+    <rect x="27" y="117" width="16" height="66"/>
+    <rect x="57" y="117" width="76" height="16"/>
+    <rect x="87" y="117" width="16" height="66"/>
+  </g>
+</svg>

mx_remote-5.5.0/docs/api.md

@@ -0,0 +1,59 @@
+# API reference
+
+Generated from the docstrings in the package. The guides cover how these fit
+together; this page is the exhaustive list.
+
+Autodoc emits reStructuredText, which the markdown parser does not read, so
+every directive below sits in an `eval-rst` block. Without it the page renders
+the directive source as prose and the build still succeeds.
+
+```{eval-rst}
+.. automodule:: mx_remote
+```
+
+## Client
+
+`Remote` owns the socket, the device registry and the background probe that
+keeps both in step with the mesh.
+
+```{eval-rst}
+.. automodule:: mx_remote.remote.Remote
+   :members:
+```
+
+## Devices, bays and callbacks
+
+A client works against these types rather than the classes implementing them:
+they are what the registry hands out and what a callback receives.
+
+```{eval-rst}
+.. automodule:: mx_remote.Interface
+   :members:
+```
+
+## Device identity
+
+```{eval-rst}
+.. automodule:: mx_remote.Uid
+   :members:
+```
+
+## Remote-control keys and actions
+
+The key and action codes a bay reports, and the target a key was aimed at.
+
+```{eval-rst}
+.. autoclass:: mx_remote.proto.Constants.RCKey
+   :members:
+   :undoc-members:
+
+.. autoclass:: mx_remote.proto.Constants.RCAction
+   :members:
+   :undoc-members:
+
+.. autoclass:: mx_remote.proto.Constants.RCType
+   :members:
+   :undoc-members:
+
+.. autodata:: mx_remote.proto.Constants.MXR_PROTOCOL_VERSION
+```

mx_remote-5.5.0/docs/audio.md

@@ -0,0 +1,36 @@
+# Audio
+
+Volume, mute and remote-control passthrough.
+
+## Volume Control
+
+```python
+bay.volume_up()
+bay.volume_down()
+bay.volume_set(volume=50)           # set to 50%
+bay.volume_set(volume=50, muted=False)
+bay.mute_set(mute=True)
+```
+
+## Remote Control
+
+Send remote control key presses and actions:
+
+```python
+from mx_remote import RCKey, RCAction
+
+# send a key press
+await bay.send_key(RCKey.KEY_SELECT)
+await bay.send_key(RCKey.KEY_UP)
+
+# send a remote control action
+await bay.tx_action(RCAction.ACTION_POWER_ON)
+await bay.tx_action(RCAction.ACTION_POWER_OFF)
+await bay.tx_action(RCAction.ACTION_POWER_TOGGLE)
+await bay.tx_action(RCAction.ACTION_VOLUME_UP)
+await bay.tx_action(RCAction.ACTION_VOLUME_DOWN)
+```
+
+---
+
+[Documentation index](README.md) | [Project README](https://github.com/opdenkamp/mx-remote#readme)

mx_remote-5.5.0/docs/callbacks.md

@@ -0,0 +1,90 @@
+# Callbacks
+
+Reacting to state changes rather than polling for them.
+
+## Callbacks
+
+Subclass `MxrCallbacks` to receive notifications when device or bay state changes:
+
+```python
+class MyCallbacks(mx_remote.MxrCallbacks):
+    def on_device_config_complete(self, dev):
+        print(f"Device ready: {dev.serial} ({dev.name})")
+
+    def on_bay_registered(self, bay):
+        print(f"Bay found: {bay.bay_label}")
+
+    def on_video_source_changed(self, bay, video_source):
+        print(f"{bay.user_name} video source -> {video_source.user_name}")
+
+    def on_audio_source_changed(self, bay, audio_source):
+        print(f"{bay.user_name} audio source -> {audio_source.user_name}")
+
+    def on_volume_changed(self, bay, volume):
+        print(f"{bay.user_name} volume: {volume}")
+
+    def on_power_changed(self, bay, power):
+        print(f"{bay.user_name} power: {power}")
+
+    def on_device_online_status_changed(self, dev, online):
+        print(f"{dev.serial} {'online' if online else 'offline'}")
+
+mx = mx_remote.Remote(callbacks=MyCallbacks())
+```
+
+Available callback methods:
+
+| Method | Trigger |
+|---|---|
+| `on_device_update` | any device property changed |
+| `on_bay_update` | any bay property changed |
+| `on_device_config_changed` | device configuration updated |
+| `on_device_config_complete` | all device configuration received |
+| `on_device_online_status_changed` | device went online/offline |
+| `on_device_temperature_changed` | temperature readings changed |
+| `on_bay_registered` | new bay discovered |
+| `on_video_source_changed` | video routing changed |
+| `on_audio_source_changed` | audio routing changed |
+| `on_volume_changed` | volume or mute status changed |
+| `on_power_changed` | CEC power status changed |
+| `on_name_changed` | user-assigned bay name changed |
+| `on_status_signal_detected_changed` | signal detect status changed |
+| `on_status_faulty_changed` | fault status changed |
+| `on_status_hidden_changed` | hidden status changed |
+| `on_status_poe_powered_changed` | PoE power status changed |
+| `on_status_hdbt_connected_changed` | HDBaseT link status changed |
+| `on_status_signal_type_changed` | signal type changed |
+| `on_status_hpd_detected_changed` | hotplug detect changed |
+| `on_status_cec_detected_changed` | CEC device detected/lost |
+| `on_status_arc_changed` | audio return channel status changed |
+| `on_key_pressed` | remote control key press received |
+| `on_action_received` | remote control action received |
+| `on_bay_linked` | virtual link created |
+| `on_bay_unlinked` | virtual link removed |
+| `on_mirror_status_changed` | bay mirroring changed |
+| `on_filter_status_changed` | bay filtering changed |
+| `on_edid_profile_changed` | EDID profile changed |
+| `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 |
+
+You can also register per-device and per-bay callbacks:
+
+```python
+def on_device_changed(device):
+    print(f"{device.serial} updated")
+
+def on_bay_changed(bay):
+    print(f"{bay.bay_label} updated")
+
+device.register_callback(on_device_changed)
+bay.register_callback(on_bay_changed)
+
+# to unregister:
+device.unregister_callback(on_device_changed)
+bay.unregister_callback(on_bay_changed)
+```
+
+---
+
+[Documentation index](README.md) | [Project README](https://github.com/opdenkamp/mx-remote#readme)