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.

mx_remote - Python 3 library for interfacing with MX Remote compatible devices.

Provides device discovery, video/audio routing, volume control, remote control key passthrough, V2IP (OneIP) streaming, and multiviewer control over a local network using UDP multicast or broadcast.

Main entry point:
>>> import mx_remote
>>> mx = mx_remote.Remote()
>>> await mx.start_async()
Key classes:

Remote Main component that manages network connections and device registry. DeviceBase A discovered device on the network (matrix, OneIP unit, amplifier). BayBase A single input or output port on a device. MxrCallbacks Subclass to receive notifications on state changes.

See README.md for full usage documentation.

Client

Remote owns the socket, the device registry and the background probe that keeps both in step with the mesh.

Remote device discovery and management over UDP multicast/broadcast.

class mx_remote.remote.Remote.Remote[source]

Bases: DeviceRegistry, ConnectionCallbacks

Main component that handles the network connections and registration of remote devices

__init__(target_ip=None, port=None, http_session=None, open_connection=True, callbacks=None, name='MXR Python', local_ip=None, broadcast=None, addr_filter=None, uid_path=None)[source]

Initialise the remote controller.

Parameters:

  • target_ip (str | None) – multicast/broadcast IP to use, or None for the default

  • port (int | None) – UDP port to use, or None for the default

  • http_session (ClientSession | None) – shared aiohttp session for API calls, or None to create one

  • open_connection (bool) – open the UDP connection immediately when True

  • callbacks (MxrCallbacks | None) – event callbacks for device state changes

  • name (str) – human-readable name advertised on the network

  • local_ip (str | None) – local interface IP to bind to, or None for any

  • broadcast (bool | None) – use broadcast instead of multicast when True

  • addr_filter (str | None) – only log frames from this IP address when set

  • uid_path (str | None) – file holding this client’s uid, or None for ~/.mxr-uid. Give concurrent clients on one host separate paths - see _load_uid

Return type:

None

property library_version: str

version of the mx_remote library

property protocol_version: int

protocol version used by this library

property net_protocol_version_max: int

highest protocol version used by devices on the network

property net_protocol_version_min: int

lowest protocol version used by devices on the network

property target_ip: str

target ip address

property local_ip: str | None

local ip address

property broadcast: bool

broadcast or multicast

property uid_raw: bytes | None

uid of this device as bytes

property uid: MxrDeviceUid

uid of this device

property name: str

device name

property callbacks: MxrCallbacks

callbacks to call when the device is updated

property http_session: ClientSession

Active HTTP client session for API commands

async update_config(callbacks=None, name=None, target_ip=None, port=None, local_ip=None, broadcast=None)[source]

Update runtime configuration, reconnecting if network parameters changed.

Parameters:
Return type:

None

has_completed_devices()[source]

Return True if at least one registered device has completed configuration.

Return type:

bool

async start_async()[source]

Start the server that listens for mx_remote frames from other devices.

Return type:

None

async stop_async()[source]

Stop the server and close all connections.

Return type:

None

async close()[source]

Close all open connections and cancel background tasks.

Return type:

None

get_by_serial(serial)[source]

Get the cached device matching the given serial number, or None.

Parameters:

serial (str)

Return type:

DeviceBase | None

get_by_uid(remote_id)[source]

Get the cached device matching the given unique id, or None.

Parameters:

remote_id (str | MxrDeviceUid | None)

Return type:

DeviceBase | None

uid_to_user_string(remote_id)[source]

return the serial of the unit if the uid is known, or the uid as string if it isn’t

Parameters:

remote_id (str | MxrDeviceUid | bytes | None)

Return type:

str

get_by_stream_ip(ip, audio=False)[source]

get a bay of a device by its V2IP stream address

Parameters:
Return type:

BayBase | None

get_bay_by_portnum(remote_id, portnum)[source]

Get the cached bay for a device, given the device id and port number.

Parameters:
Return type:

BayBase | None

get_bay_by_portname(remote_id, portname)[source]

get a bay of a device by its unique id and port name

Parameters:
Return type:

BayBase | None

linked bay configurations for all devices

transmit(data)[source]

Transmit raw data over the UDP connection. Returns bytes sent.

Parameters:

data (bytes)

Return type:

int

tx_discover()[source]

Transmit a discover frame. All remotes will respond with a hello frame.

Return type:

int

tx_hello()[source]

Transmit a hello frame to announce this device on the network.

Return type:

int

on_connection_made()[source]

Callback invoked after ConnectionAsync has started the server.

Return type:

None

process_frame(timestamp, data, addr)[source]

Decode and process a received mx_remote frame.

Parameters:
Return type:

None

on_datagram_received(data, addr)[source]

Called when a UDP frame was received.

Parameters:
Return type:

None

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.

mx_remote.Interface.mxr_valid_addresses()[source]

Get the list of valid local_ip addresses that can be used

Returns:

list of IP addressses that can be used for the local_ip parameter

Return type:

addresses (list[str])

mx_remote.Interface.mxr_broadcast_address(local_ip=None)[source]

Get the broadcast address for the interface matching local_ip, or the first non-loopback interface.

Parameters:

local_ip (str | None)

Return type:

str | None

class mx_remote.Interface.DeviceStatus[source]

Bases: IntEnum

Status of a device on the network

ONLINE = 0

unit is online

OFFLINE = 1

unit is offline

REBOOTING = 2

unit indicated that it is going to reboot

BOOTING = 3

unit is booting

INACTIVE = 4

bay is inactive (V2IP encoder/decoder idle)

__new__(value)
class mx_remote.Interface.PowerStatus[source]

Bases: IntEnum

__new__(value)
class mx_remote.Interface.HiddenStatus[source]

Bases: IntEnum

__new__(value)
class mx_remote.Interface.ConnectStatus[source]

Bases: IntEnum

__new__(value)
class mx_remote.Interface.VideoColourSpace[source]

Bases: IntEnum

Video colour space encoding format.

__new__(value)
class mx_remote.Interface.VideoSignalDetails[source]

Bases: object

Video format of a bay: CTA-861 svd, colour space, bit depth, frame rate kind.

from_report says where it came from, because the two sources do not carry the same currency. A signal status report is the live format and arrives on a signal change. The bay config snapshot is a fallback for a bay no report has been seen for: it refreshes on the bay config broadcast cycle, so it can lag a change by a broadcast interval.

bpp is a bit depth in both cases, not a wire index. None means no format is set; 0 means one is set whose depth is not known, and those are different answers.

__init__(svd, colour, bpp, non_int, from_report)[source]
Parameters:
Return type:

None

property svd: int | None

CTA-861 short video descriptor, or None when no format is set.

property colour: VideoColourSpace | None

Colour space, or None when no format is set or the value is unknown to this build.

property bpp: int | None

Bit depth, 0 when a format is set whose depth is not known.

property non_int: bool | None

True for a non-integer (1000/1001) frame rate.

property from_report: bool

True when this came from a signal status report rather than the bay config snapshot.

class mx_remote.Interface.AmpDolbySettings[source]

Bases: object

Dolby Digital settings for an amplifier

mode: int

Dolby mode

pcm_upmix: bool

PCM upmixing enabled

dolby_detected: bool

Dolby 5.1 signal detected

pcm_upmix_active: bool

PCM upmixing active

class mx_remote.Interface.AmpZoneSettings[source]

Bases: object

Zone specific settings for an amplifier input/output

gain_left: int

gain level left channel

gain_right: int

gain level right channel

volume_min: int

minimum volume level

volume_max: int

maximum volume level

delay_left: int

audio delay left channel (ms)

delay_right: int

audio delay right channel (ms)

bass: int

bass level

treble: int

treble level

bridged: int

bridging mode setting

power_mode: int

auto power off setting

power_level: int

auto power off level

power_timeout: int

auto power off timeout

eq_left: list[int]

equalizer left channel

eq_right: list[int]

equalizer right channel

class mx_remote.Interface.V2IPAudioFormat[source]

Bases: object

V2IP audio format (sample rate + channels). Zero values mean “use firmware defaults”.

__init__(sample_rate=0, channels=0)[source]
Parameters:

  • sample_rate (int)

  • channels (int)

Return type:

None

property sample_rate: int

Sample rate in Hz, or 0 to fall back to the firmware default (48000).

property channels: int

Channel count 1..8, or 0 to fall back to the firmware default (2).

class mx_remote.Interface.V2IPStreamSource[source]

Bases: ABC

V2IP multicast IP address and port number

abstract property label: str

user friendly description of this stream

abstract property ip: str

multicast IP address

abstract property port: int

UDP port number

class mx_remote.Interface.V2IPStreamSources[source]

Bases: object

All V2IP multicast IP addresses and port numbers used by a device

abstract property uid: MxrDeviceUid | None

uid of the originating source device, when known

abstract property video: V2IPStreamSource

video stream source

abstract property audio: V2IPStreamSource

audio stream source

abstract property anc: V2IPStreamSource

ancillary stream source

abstract property arc: V2IPStreamSource | None

audio return stream source

property valid: bool

True when this entry carries a usable address.

Video and anc must both be multicast with a non-zero port; audio is optional and rides along. A sender without MXR_FEATURE_CONFIG_INITIALISED can put stack contents in bay 0’s addresses under its own uid, which rarely satisfy both halves of this test.

property cleared: bool

True when every stream is zeroed, which reports that the source is gone.

Distinct from an entry that is neither valid nor cleared, which is malformed. Treating a cleared entry as unusable discards the only signal that a source went away.

class mx_remote.Interface.V2IPStreamSourcesList[source]

Bases: list[V2IPStreamSources]

list of V2IP sources

class mx_remote.Interface.AudioChangeSource[source]

Bases: ABC

class mx_remote.Interface.AudioEndpoint[source]

Bases: ABC

__init__(container)[source]
Parameters:

container (AudioEndpoints)

Return type:

None

Bases: ABC

Bases: ABC

class mx_remote.Interface.DeviceList[source]

Bases: list[MxrDeviceUid]

__init__(data=None)[source]
Parameters:

data (bytes | None)

append(item)[source]

Append object to the end of the list.

Parameters:

item (MxrDeviceUid)

Return type:

None

class mx_remote.Interface.FilteredDevices[source]

Bases: DeviceList

list of filtered devices

class mx_remote.Interface.BayBase[source]

Bases: ABC

A bay (input/output) of an mx_remote device

abstract property status: DeviceStatus

bay status

abstract property callbacks: MxrCallbacks

mx_remote callbacks

abstract property device: DeviceBase

device to which this bay belongs

abstract property bay_uid: MxrBayUid

unique id of this bay

abstract property port: int

port number

abstract property is_local: bool

local or remote bay

abstract property bay_name: str

bay name for logging (mode / number)

abstract property user_name: str

name set up by the user

abstract property has_default_name: bool

default name not changed by the user

abstract property edid_profile: EdidProfile | None

edid profile used by the source

abstract property bay_label: str

user friendly label for this bay

abstract property features: BayFeaturesMask

List of supported features as strings

abstract property is_v2ip_remote: bool

V2IP remote bay

abstract property dolby_input: str | None

Dolby Digital input

property dolby_input_bay: BayBase | None

Dolby Digital input bay used by this audio output bay

abstract property has_volume_control: bool

Volume control supported by this bay

abstract property is_input: bool

Source bay

abstract property is_output: bool

Sink bay

abstract property mode: str

Bay mode name

property other_mode: str

Bay mode name of the opposite side (so Output if this bay is an Input)

abstract property bay: int

Bay number

abstract property available: bool

True if available

abstract property is_hdmi: bool

True if this is an HDMI input or output

abstract property is_hdbaset: bool

True if this is a HDBaseT bay

abstract property is_audio: bool

True if this is audio input or output bay

abstract property video_source: BayBase | None

Current video source (output only)

abstract property video_route_endpoint: str | None

port’ literal when the sink is subscribed to a multicast that does not map to any registered input bay; else None.

Type:

Current video route as ‘ip

abstract property available_video_sources: list[BayBase]

Video sources that can be selected

abstract property audio_source: BayBase | None

Current audio source (output only)

abstract property audio_route_endpoint: str | None

port’ literal when the sink is subscribed to a multicast that does not map to any registered input bay; else None.

Type:

Current audio route as ‘ip

abstract property available_audio_sources: list[BayBase]

Audio sources that can be selected

abstract property powered_on: bool

True the connected device supports CEC and reports that the device is powered on

abstract property powered_off: bool

True the connected device supports CEC and reports that the device is powered off

abstract property power_status: PowerStatus

Power status

abstract property faulty: bool

True if a fault was detected

abstract property hidden: bool

True if flagged as hidden

abstract property poe_powered: bool

True if PoE has been enabled (HDBaseT only)

abstract property hdbt_connected: bool

HDBaseT receiver connected

abstract property signal_detected: bool

Video signal detected (matrix/oneip) or audio signal detected (proamp)

abstract property signal_type: str

Audio or video signal type

abstract property video_details: VideoSignalDetails | None

Current video format, or None if neither source has carried one.

Prefers the signal status report, which arrives on a signal change, and falls back to the bay config snapshot for a bay no report has been seen for. Read from_report to tell which one this is.

abstract property hpd_detected: bool

Hotplug detected

abstract property cec_detected: bool

Connected device supports HDMI-CEC

abstract property mirroring: BayMirrorStatus

Bay mirroring status

abstract property filtered: FilteredDevices

Filtered bays

abstract property arc: str

Audio return channel status

abstract property volume: int | None

Current volume level (percentage)

abstract property muted: bool | None

True if audio has been muted, None if not available

abstract property online: bool

True if online

abstract property rebooting: bool

True if rebooting

abstract property booting: bool

True if booting

abstract property is_primary: bool

True if this bay is the primary bay in a mirroring setup

abstract property primary: BayBase

The primary bay in a mirroring setup

abstract property v2ip_source: V2IPStreamSources | None

V2IP source address information

abstract property v2ip_uid: MxrDeviceUid | None

Remote V2IP device uid

abstract property v2ip_device: DeviceBase | None

Remote V2IP device

mx-remote virtual link configuration (proamp<->matrix)

abstract property linked_bay: BayBase | None

linked bay if an mx-remote virtual link has been set up

mx-remote virtual link configured (proamp<->matrix)

mx-remote virtual link connected (proamp<->matrix)

abstract property volume_status: VolumeMuteStatus | None

volume and mute status

abstract property amp_settings: AmpZoneSettings | None

proamp zone settings

abstract property encoder_disabled: bool

video/audio encoder disabled

abstract property decoder_disabled: bool

video/audio decoder disabled

abstract property audio_endpoint: AudioEndpoint | None

primary audio endpoint. currently v2ip only

abstractmethod async set_name(name)[source]

change the name of abay

Parameters:

name (str)

Return type:

bool

abstractmethod async select_video_source(port, opt=True)[source]

change the video source of an output bay

Parameters:
Return type:

bool

abstractmethod async select_video_source_by_user_name(name, opt=True)[source]

change the video source of an output bay

Parameters:
Return type:

bool

abstractmethod async select_audio_source(source, endpoint=None, audio_fmt=None)[source]

change the audio source of an output bay

Parameters:
Return type:

bool

abstractmethod async select_edid_profile(profile)[source]

change the edid profile of an input bay

Parameters:

profile (EdidProfile)

Return type:

bool

abstractmethod async set_hidden(hidden)[source]

change the hidden status of a bay

Parameters:

hidden (bool)

Return type:

bool

abstractmethod async power_on()[source]

power on the remote device if CEC is supported

Return type:

bool

abstractmethod async power_off()[source]

power off the remote device if CEC is supported

Return type:

bool

abstractmethod volume_up()[source]

change the volume if supported

Return type:

bool

abstractmethod volume_down()[source]

change the volume if supported

Return type:

bool

abstractmethod volume_set(volume, muted=None)[source]

change the volume if supported

Parameters:
Return type:

bool

abstractmethod mute_set(mute)[source]

change the mute status if supported

Parameters:

mute (bool)

Return type:

bool

abstractmethod async send_key(key)[source]

send a remote control key press to the device

Parameters:

key (int)

Return type:

bool

abstractmethod register_callback(callback)[source]

register a callback, called when the bay state changed

Parameters:

callback (Callable[[BayBase], None])

Return type:

None

abstractmethod unregister_callback(callback)[source]

unregister a callback

Parameters:

callback (Callable[[BayBase], None])

Return type:

None

abstractmethod call_callbacks()[source]

notify callbacks that this bay has changed

Return type:

None

class mx_remote.Interface.DeviceV2IPScalingSettings[source]

Bases: ABC

abstract property mode: int

Scaling mode, carried only when flags has MXR_SCALING_FLAG_MODE_VALID

abstract property refresh: int

Refresh rate paired with mode, under the same MXR_SCALING_FLAG_MODE_VALID marker

abstract property flags: int

mxr_scaling_config.flags.

MXR_SCALING_FLAG_MODE_VALID and MXR_SCALING_FLAG_OPTIONS_VALID mark which half a sender meant to send, and are separately valid; a sender setting neither is offering no scaling at all. MXR_SCALING_FLAG_AUTO_SCALING is the only option bit with a defined meaning.

mx_remote.Interface.v2ip_stream_valid(stream)[source]

True when a stream source carries an address a frame actually meant to send.

Mirrors the firmware’s own test: a multicast ip and a non-zero port. A controller write that offers no addresses leaves the block zeroed, which fails both tests.

Parameters:

stream (V2IPStreamSource | None)

Return type:

bool

mx_remote.Interface.v2ip_av_source_valid(video, anc)[source]

True when an av source block carries addresses a frame meant to send.

Mirrors the firmware’s own test: video and anc must both be valid, audio is optional and is carried along with them.

Parameters:
Return type:

bool

mx_remote.Interface.v2ip_stream_cleared(stream)[source]

True when a stream source is zeroed, which is how “no source” is spelled.

Parameters:

stream (V2IPStreamSource | None)

Return type:

bool

class mx_remote.Interface.V2IPScalingSettings[source]

Bases: DeviceV2IPScalingSettings

Plain holder for a merged mxr_scaling_config.

__init__(mode, refresh, flags)[source]
Parameters:
Return type:

None

property mode: int

Scaling mode, carried only when flags has MXR_SCALING_FLAG_MODE_VALID

property refresh: int

Refresh rate paired with mode, under the same MXR_SCALING_FLAG_MODE_VALID marker

property flags: int

mxr_scaling_config.flags.

MXR_SCALING_FLAG_MODE_VALID and MXR_SCALING_FLAG_OPTIONS_VALID mark which half a sender meant to send, and are separately valid; a sender setting neither is offering no scaling at all. MXR_SCALING_FLAG_AUTO_SCALING is the only option bit with a defined meaning.

class mx_remote.Interface.V2IPDscpConfig[source]

Bases: object

Per-stream DSCP marking carried in a V2IP device configuration.

DSCP 0 (CS0) is a legal marking, so each wire byte carries a set bit alongside its value and a stream whose byte is unset reads back as None here. Firmware treats the marking as all-or-nothing: it only applies one when all three streams carry a value, and otherwise falls back to CS2 (V2IP_DSCP_DEFAULT) - complete reports which case a frame is in.

__init__(video, audio, anc)[source]
Parameters:

  • video (int | None)

  • audio (int | None)

  • anc (int | None)

Return type:

None

property carried: bool

True when this frame carried a marking at all.

Gated on the video byte alone, matching the firmware cache, which stores all three bytes verbatim. Not complete: a partial set does overwrite a peer’s marking, so treating it as absent would report a marking the peer does not hold.

property complete: bool

True when all three streams carry a marking.

Whether a marking is applied, as opposed to carried: firmware falls back to CS2 on all three streams unless every byte is set, so a partial set is cached and reported but never applied.

class mx_remote.Interface.DeviceV2IPDetails[source]

Bases: object

V2IP stream source details for a device

__init__(video, audio, anc, arc, tx_rate, scaling, dscp=None)[source]
Parameters:
Return type:

None

property tx_rate: int | None

Source rate this device transmits at, or None if none is known.

Only a rate within V2IP_SOURCE_RATE_MIN..MAX is one a sender meant to send; anything else is an absent offer rather than a rate, and merge() keeps the previously known value instead of caching what was on the wire.

property dscp: V2IPDscpConfig | None

Per-stream DSCP marking, or None from peers that predate it.

merge(previous)[source]

Carry forward every field this frame did not carry.

A controller writing one field of a peer’s config leaves the others zeroed on the wire, so each is applied only behind its own validity marker. See FrameV2IPDeviceConfiguration for the markers.

Parameters:

previous (DeviceV2IPDetails | None)

Return type:

DeviceV2IPDetails

class mx_remote.Interface.DeviceV2IPSink[source]

Bases: object

A V2IP sink’s effective multicast subscriptions and resolved audio format.

Mirrors the sink-side state broadcast alongside v2ip_device_config updates and manual-switch frames. addresses is None when no active route is announced; when present, each stream may still carry an all-zero ip when that stream is inactive. audio_fmt carries the resolved sink audio format (zero fields fall back to firmware defaults of 48kHz / 2 channels).

__init__(addresses, audio_fmt)[source]
Parameters:
Return type:

None

class mx_remote.Interface.UtpLinkErrorStatus[source]

Bases: ABC

UTP link error status bits

abstract property in_error: bool

rx errors detected

abstract property in_fcs_error: bool

rx FCS errors detected

abstract property in_collision: bool

rx collisions detected

abstract property out_deferred: bool

tx deferred detected

abstract property out_excessive: bool

tx excessive detected

abstract property polarity_error: bool

polarity differences between pairs detected

abstract property skew_warning: bool

clock skew > 8 detected

abstract property length_warning: bool

different pair lengths detected

class mx_remote.Interface.UtpCableStatus[source]

Bases: ABC

‘ UTP cable pair status

abstract property polarity: bool

positive or negative polarity

abstract property pair: int

pair number

abstract property skew: int

detected clock skew

abstract property length: int

detected length in meters

class mx_remote.Interface.NetworkPortStatus[source]

Bases: ABC

detailed status of a network port

property port: int

port number

property errors: UtpLinkErrorStatus | None

link error status

property vct_status: list[str] | None

virtual cable test results

link speed

full duplex or half duplex

property name: str

description of the port

property ip: str | None

IP address

property querier: str | None

detected IGMP querier or 0.0.0.0 if not detected

property cable_status: list[UtpCableStatus] | None

utp cable pair status

property mac_address: str | None

mac address of supported devices

class mx_remote.Interface.SystemTemperature[source]

Bases: list[int]

system temperature

class mx_remote.Interface.DeviceBase[source]

Bases: ABC

an mx_remote device on the network

abstract property status: DeviceStatus

device status

abstract property name: str

device name

abstract property registry: DeviceRegistry

local device information registry

abstract property configuration_complete: bool

check whether all configuration info for this device has been received

abstract property model_name: str

Model name

abstract property callbacks: MxrCallbacks

callbacks for this device

abstract property remote_id: MxrDeviceUid

unique id

abstract property version: str

firmware version

abstract property address: str

IP address

abstract property features: DeviceFeature | None

supported features

abstract property serial: str

serial number

abstract property bays: dict[int, BayBase]

device inputs and outputs

abstract property inputs: dict[str, BayBase]

device inputs

abstract property nb_inputs: int

number of inputs

abstract property first_input: BayBase | None

the first local input

abstract property outputs: dict[str, BayBase]

device outputs

abstract property nb_outputs: int

number of outputs

abstract property first_output: BayBase | None

the first local output

abstract property online: bool

True if online

abstract property rebooting: bool

True if rebooting

abstract property booting: bool

True if booting

abstract property is_amp: bool

True if as an audio amplifier

abstract property amp_dolby_channels: int

number of dolby input channels

abstract property nb_hdbt: int

number of HDBaseT inputs and outputs

abstract property is_v2ip: bool

True if this a OneIP device

abstract property has_local_source: bool

True if this device has at least 1 local source

abstract property has_local_sink: bool

True if this device has at least 1 local sink

abstract property is_video_matrix: bool

True if this device supports video matrixing

abstract property is_audio_matrix: bool

True if this device supports audio matrixing

abstract property temperatures: dict[str, int]

temperature sensor reports

abstract property v2ip_sources: V2IPStreamSourcesList | None

V2IP stream source addresses

abstract property v2ip_stats: V2IPDeviceStats | None

V2IP encoder/decoder statistics

abstract property v2ip_details: DeviceV2IPDetails | None

V2IP encoder/decoder configuration

abstract property v2ip_sink: DeviceV2IPSink | None

V2IP sink-side multicast subscriptions and resolved audio format (None until first announced)

abstract property v2ip_source_local: V2IPStreamSources | None

local v2ip source addresses

abstract property mesh_master: DeviceBase | None

The device that is the master device in the V2IP mesh to which this device belongs

abstract property protocol: int

Highest protocol version this device advertises, or 0 if none has been seen.

abstractmethod supports_opcode(opcode)[source]

True when this device can receive opcode.

Each opcode has a minimum protocol version, and a device whose cap is lower drops the frame without answering - there is no NAK at any layer, so an ungated send looks like success. A device that has advertised no version yet returns True: refusing on that would break every send made before the first hello arrives, and the firmware itself only compares against a version it has.

Parameters:

opcode (int)

Return type:

bool

abstract property is_mesh_master: bool

True if this device is the master device of a V2IP mesh

abstract property is_mesh_member: bool

True if this device is a member of a V2IP mesh

abstract property is_oneip_multiviewer: bool

True if this device is a OneIP Multiviewer

abstract property supports_video_wall: bool

True if this sink can crop its source to a video wall window (MXR_FEATURE_VIDEO_WALL)

abstract property config_initialised: bool

True if every configuration block this device broadcasts is fully written.

A device without MXR_FEATURE_CONFIG_INITIALISED builds some config payloads from stack locals it never zeroes, so these are unreliable from it: the scaling block in V2IP_DEVICE_CFG, bay 0’s addresses in SYS_BAY_V2IP_SOURCES, and the padding beside the rc target in RC_SETTINGS. None of that is detectable within a frame.

abstract property is_oneip_tz: bool

True if this device is a OneIP Transceiver

abstract property is_oneip_tx: bool

True if this device is a OneIP Transmitter

abstract property is_oneip_rx: bool

True if this device is a OneIP Receiver

abstract property crashed_recently: bool

True if a crash caused this device to reboot

abstract property dolby_settings: AmpDolbySettings | None

Dolby Digital settings (proamp)

abstract property v2ip_firmware_versions: dict[FirmwareType, FirmwareVersion] | None

V2IP FPGA firmware versions

abstractmethod v2ip_source(bay)[source]

Get the V2IP source addresses for the given bay

Parameters:

bay (BayBase)

Return type:

V2IPStreamSources | None

abstractmethod get_by_portnum(portnum)[source]

Get the bay with the given number on this device

Parameters:

portnum (int)

Return type:

BayBase | None

abstractmethod get_by_portname(portname)[source]

Get the bay with the given port name (not user set name) on this device

Parameters:

portname (str)

Return type:

BayBase | None

abstract property network_status: dict[int, NetworkPortStatus]

network status for all ports

abstract property status_message: str

system health status

internal callback

Return type:

None

abstractmethod async get_api(uri)[source]

call an HTTP API method and return the result

Parameters:

uri (str)

Return type:

dict[str, Any] | None

abstractmethod register_callback(callback)[source]

register a callback, called when the device state changed

Parameters:

callback (Callable[[DeviceBase], None])

Return type:

None

abstractmethod unregister_callback(callback)[source]

unregister a callback

Parameters:

callback (Callable[[DeviceBase], None])

Return type:

None

abstractmethod async reboot()[source]

reboot this device

Return type:

bool

abstractmethod async mesh_promote()[source]

promote to mesh master

Return type:

bool

abstractmethod async mesh_remove()[source]

remove from mesh

Return type:

bool

abstractmethod async read_stats(enable)[source]

start or stop dumping stats

Parameters:

enable (bool)

Return type:

bool

abstractmethod async get_log()[source]

read the log from the device and return it as string

Return type:

str | None

class mx_remote.Interface.Multiviewer[source]

Bases: ABC

Bases: object

a virtual mx_remote link between bays, like an amp output that’s linked to a oneip sink

__init__(registry, bay, linked_serial, linked_bay, features)[source]
Parameters:
Return type:

None

property serial: str

serial number of the linked device

property linked_bay_name: str

bay name of the linked bay

property bay: BayBase

origin bay

property linked_bay: BayBase | None

linked bay

property linked: bool

True if a link has been set up

the link instance of the linked bay

property connected: bool

True if both sides have been set up

property online: bool

True if both sides are online

property is_audio: bool

True if this is an audio link

property is_video: bool

True if this is a video link

property features: list[str]

supported link features as list of string

property features_mask: LinkFeature

supported link features as bitmask

Bases: object

linked bay configurations for all devices

__init__(registry)[source]
Parameters:

registry (DeviceRegistry)

Return type:

None

class mx_remote.Interface.DeviceRegistry[source]

Bases: ABC

all mx_remote devices on the network

abstract property local_ip: str | None

local ip address

abstract property broadcast: bool

broadcast or multicast

abstract property library_version: str

version of the mx_remote library

abstract property protocol_version: int

protocol version used by this library

abstract property net_protocol_version_max: int

highest protocol version used by devices on the network

abstract property net_protocol_version_min: int

lowest protocol version used by devices on the network

abstract property uid_raw: bytes | None

uid of this device as bytes

property uid: MxrDeviceUid

uid of this device

abstract property name: str

device name

abstract property callbacks: MxrCallbacks

callbacks to call when the device is updated

abstractmethod transmit(data)[source]

transmit data to this device (broadcast/multicast)

Parameters:

data (bytes)

Return type:

int

linked bay configurations for all devices

abstractmethod get_by_serial(serial)[source]

get a device by its serial number

Parameters:

serial (str)

Return type:

DeviceBase | None

abstractmethod get_by_uid(remote_id)[source]

get a device by its unique id

Parameters:

remote_id (str | MxrDeviceUid | None)

Return type:

DeviceBase | None

abstractmethod uid_to_user_string(remote_id)[source]

return the serial of the unit if the uid is known, or the uid as string if it isn’t

Parameters:

remote_id (str | MxrDeviceUid | bytes | None)

Return type:

str

abstractmethod get_bay_by_portnum(remote_id, portnum)[source]

get a bay of a device by its unique id and port number

Parameters:
Return type:

BayBase | None

abstractmethod get_bay_by_portname(remote_id, portname)[source]

get a bay of a device by its unique id and port name

Parameters:
Return type:

BayBase | None

abstractmethod get_by_stream_ip(ip, audio=False)[source]

get a bay of a device by its V2IP stream address

Parameters:
Return type:

BayBase | None

class mx_remote.Interface.ConnectionCallbacks[source]

Bases: ABC

property target_ip: str

target ip address

abstractmethod on_connection_made()[source]

called when the socket was opened

Return type:

None

abstractmethod on_datagram_received(data, addr)[source]

called when a datagram was received

Parameters:
Return type:

None

class mx_remote.Interface.MxrCallbacks[source]

Bases: object

callbacks that can be used by an external application to get notified when a status changes

on_device_update(dev)[source]

called when properties of ‘dev’ have been updated

Parameters:

dev (DeviceBase)

Return type:

None

on_bay_update(bay)[source]

called when properties of ‘bay’ have been updated

Parameters:

bay (BayBase)

Return type:

None

on_device_config_changed(dev)[source]

called when device configuration properties of ‘dev’ have been updated

Parameters:

dev (DeviceBase)

Return type:

None

on_device_config_complete(dev)[source]

called when device configuration of ‘dev’ had been received fully

Parameters:

dev (DeviceBase)

Return type:

None

on_device_online_status_changed(dev, online)[source]

called when the online status of ‘dev’ changed

Parameters:
Return type:

None

on_bay_registered(bay)[source]

called when a new bay was registered by mx_remote

Parameters:

bay (BayBase)

Return type:

None

on_device_temperature_changed(dev)[source]

called when the temperature values of ‘dev’ changed

Parameters:

dev (DeviceBase)

Return type:

None

on_power_changed(bay, power)[source]

called when the power status of ‘bay’ changed

Parameters:
Return type:

None

on_name_changed(bay, user_name)[source]

called when the name that’s set up by the user of ‘bay’ changed

Parameters:
Return type:

None

on_status_signal_detected_changed(bay, val)[source]

called when the signal detect status of ‘bay’ changed

Parameters:
Return type:

None

on_status_faulty_changed(bay, val)[source]

called when the fault status of ‘bay’ changed

Parameters:
Return type:

None

on_status_hidden_changed(bay, val)[source]

called when the hidden status of ‘bay’ changed

Parameters:
Return type:

None

on_status_poe_powered_changed(bay, val)[source]

called when the PoE power status of ‘bay’ changed

Parameters:
Return type:

None

on_status_hdbt_connected_changed(bay, val)[source]

called when the HDBaseT connection status of ‘bay’ changed

Parameters:
Return type:

None

on_status_signal_type_changed(bay, val)[source]

called when the detected signal of ‘bay’ changed

Parameters:
Return type:

None

on_status_hpd_detected_changed(bay, val)[source]

called when the HPD value of ‘bay’ changed

Parameters:
Return type:

None

on_status_cec_detected_changed(bay, val)[source]

called when a CEC device was detected on ‘bay’

Parameters:
Return type:

None

on_status_arc_changed(bay, val)[source]

called when the audio return channel status of ‘bay’ changed

Parameters:
Return type:

None

on_volume_changed(bay, volume)[source]

called when the volume/mute status of ‘bay’ changed

Parameters:

  • bay (BayBase)

  • volume (VolumeMuteStatus | None)

Return type:

None

on_key_pressed(bay, key)[source]

called when a key press was detected on ‘bay’

Parameters:
Return type:

None

on_action_received(bay, action)[source]

called when a remote control action was detected on ‘bay’

Parameters:
Return type:

None

on_video_source_changed(bay, video_source)[source]

called when a video source changed was detected on ‘bay’

Parameters:
Return type:

None

on_audio_source_changed(bay, audio_source)[source]

called when an audio source changed was detected on ‘bay’

Parameters:
Return type:

None

on_bay_linked(bay, linked_serial, linked_bay, features)[source]

called when a bay link was detected

Parameters:
Return type:

None

on_bay_unlinked(bay, linked_serial, linked_bay)[source]

called when a bay link was removed

Parameters:
Return type:

None

on_mirror_status_changed(bay, mirror)[source]

called when a bay mirroring setup change was detected

Parameters:

  • bay (BayBase)

  • mirror (BayMirrorStatus)

Return type:

None

on_filter_status_changed(bay, filtered)[source]

called when a bay filtering setup change was detected

Parameters:
Return type:

None

on_edid_profile_changed(bay, profile)[source]

called when a source EDID profile was changed

Parameters:

  • bay (BayBase)

  • profile (EdidProfile | None)

Return type:

None

on_rc_type_changed(bay, rc_type)[source]

called when a source remote control type was changed

Parameters:
Return type:

None

on_amp_zone_settings_changed(bay, settings)[source]

called when amp zone settings were changed

Parameters:
Return type:

None

on_amp_dolby_settings_changed(device, settings)[source]

called when amp dolby settings were changed

Parameters:
Return type:

None

Device identity

Unique device and bay identifier types for mx_remote.

class mx_remote.Uid.MxrDeviceUid[source]

Bases: object

Unique ID of an mx_remote device on the network

__init__(value)[source]
Parameters:

value (object)

Return type:

None

property value: str

value as human readble string

property empty: bool

True if all 0

property byte_value: bytes

value as bytes

class mx_remote.Uid.MxrBayUidOld[source]

Bases: object

Legacy bay identifier using serial number and port name.

__init__(serial, port_name)[source]
Parameters:

  • serial (str)

  • port_name (str)

Return type:

None

class mx_remote.Uid.MxrBayUid[source]

Bases: object

Bay identifier using a device UID and port number.

__init__(device, port_number)[source]
Parameters:
Return type:

None

Remote-control keys and actions

The key and action codes a bay reports, and the target a key was aimed at.

class mx_remote.proto.Constants.RCKey[source]

Bases: IntEnum

Remote control key codes (CEC/IR).

KEY_0 = 0
KEY_1 = 1
KEY_2 = 2
KEY_3 = 3
KEY_4 = 4
KEY_5 = 5
KEY_6 = 6
KEY_7 = 7
KEY_8 = 8
KEY_9 = 9
KEY_SELECT = 10
KEY_BACK = 11
KEY_UP = 12
KEY_DOWN = 13
KEY_LEFT = 14
KEY_RIGHT = 15
KEY_MENU = 16
KEY_CONTENT_MENU = 17
KEY_CHANNEL_UP = 18
KEY_CHANNEL_DOWN = 19
KEY_PLAY = 20
KEY_PAUSE = 21
KEY_STOP = 22
KEY_RECORD = 23
KEY_FAST_FORWARD = 24
KEY_REWIND = 25
KEY_RED = 26
KEY_GREEN = 27
KEY_YELLOW = 28
KEY_BLUE = 29
KEY_HELP = 30
KEY_INFORMATION = 31
KEY_TEXT = 32
KEY_GUIDE = 33
KEY_VIDEO_ON_DEMAND = 34
KEY_PREVIOUS_CHANNEL = 80
KEY_3D_MODE = 81
KEY_SUBTITLE = 82
KEY_SOUND_SELECT = 83
KEY_INPUT_SELECT = 84
KEY_EJECT = 85
KEY_NEXT_CHAPTER = 86
KEY_PREVIOUS_CHAPTER = 87
KEY_CUSTOM_CEC = 1280
KEY_INTERACTIVE = 128
KEY_SKY = 130
KEY_CUSTOM_SKY = 2048
__new__(value)
class mx_remote.proto.Constants.RCAction[source]

Bases: IntEnum

Remote control actions.

ACTION_POWER_TOGGLE = 0
ACTION_POWER_ON = 1
ACTION_POWER_OFF = 2
ACTION_VOLUME_DOWN = 3
ACTION_VOLUME_UP = 4
ACTION_VOLUME_MUTE = 5
__new__(value)
class mx_remote.proto.Constants.RCType[source]

Bases: IntEnum

Remote control protocol type.

IR = 0
CEC = 1
SKY_UK = 2
TIVO = 3
KODI = 4
DISH = 5
DIRECTV = 6
MX_REMOTE = 7
static values()[source]
Return type:

dict[int, str]

__new__(value)
mx_remote.proto.Constants.MXR_PROTOCOL_VERSION = 41

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.

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.