Crate mx_remote

Expand description

Client library for Pulse-Eight MatrixOS devices (neo matrices, OneIP/V2IP units, ProAmp8 amplifiers) over UDP multicast/broadcast.

Devices announce themselves and their bays, report signal, audio, streaming and power state as it changes, and accept routing and configuration commands. A Remote discovers them, keeps a snapshot of what they have reported, and sends those commands.

§Getting started

use std::sync::{Arc, OnceLock};

use mx_remote::{Config, DeviceUid, EventHandler, Remote};

// A handler is handed to the client that will call it, so it cannot hold
// one at the time it is built. It is filled in before the client starts,
// which is before anything can call back.
static CLIENT: OnceLock<Arc<Remote>> = OnceLock::new();

struct Printer;

impl EventHandler for Printer {
    fn on_device_update(&self, device: DeviceUid) {
        let Some(info) = CLIENT.get().and_then(|c| c.device(device)) else {
            return;
        };
        println!("{device} {} {}", info.model, info.name);
    }
}

let remote = Arc::new(Remote::new(Config::default(), Arc::new(Printer))?);
let _ = CLIENT.set(Arc::clone(&remote));
remote.start()?;

Config::default discovers over multicast on the interface the host picks, which is the right answer on a single-homed machine and arbitrary on any other. cargo run --example discover is the program above, complete.

§Events say what moved

Every method on EventHandler has a default that does nothing, so a caller implements only what it acts on. Most carry just the identifier of the device or bay that changed: the snapshot read back from Remote is the same state the event was derived from, and can only be fresher. EventHandler::on_device_update and EventHandler::on_bay_update fire after every event at their level, which is enough for a caller that only wants to know that something moved.

Handler methods run on the receive thread, so they should return quickly.

§Values arrive as they were sent

Every enumeration here is a newtype over its wire integer with named constants rather than a closed set, so a value from firmware newer than this library reaches the caller unchanged instead of being folded onto a neighbour.

An Option on a snapshot is a field the device has not reported yet, which is a different answer from one reported as zero or false. Zero is a valid reading for most of them, so a confidently wrong value would be worse than an absent one.

§Threads

Remote::start takes a receive thread and a timer thread, and Remote::close - or dropping the Remote - stops and joins them. There is no async runtime.

Structs§

ActionTransmitRequest: Asks one device to perform a remote-control action.
AmpDolbySettings: The Dolby processing state of a ProAmp8.
AmpZoneSettings: A ProAmp8 zone’s gain, delay, tone and power settings.
AudioChangeSource: An audio input-selection change: which source endpoint a sink endpoint was switched to.
AudioClip: Reports that a bay detected audio clipping.
AudioEndpoint: One audio endpoint: an input, an output, or a processing node between them.
AudioEndpoints: The audio endpoints a device reports, in the order it reported them.
AudioFeatures: What one audio endpoint can do.
AudioLink: A link from an audio endpoint on this device to one on another.
BayFeatures: Capabilities of a single bay.
BayInfo: What a bay is, and what is connected to it.
BayMirrorStatus: Whether an output bay mirrors another device’s output, and which one.
BayNameChange: Asks a device to rename one of its bays.
BaySignalDetails: What a bay signal status report carries beyond the signal-detected flag and the human-readable signal type.
BayStatus: Live status flags of a single bay.
BayUid: Identifies a single bay (port) by its owning device and port number.
Config: How a Remote finds the network.
DeviceFeature: Capabilities a device reports in its hello frame.
DeviceInfo: What a device is, and what it is doing.
DeviceUid: The 16-byte unique identifier of an MX Remote device on the network.
DeviceV2ipDetails: The local encoder/decoder configuration of a V2IP device.
DeviceV2ipSink: The sink-side route a V2IP device is currently subscribed to.
EdidProfile: An EDID preset selectable on an HDMI input.
EdidProfileChange: Asks a device to switch its input EDID profile.
EdidRecord: One EDID block from a DEV_EDID reply.
EdidRequest: Asks one device for its EDID.
FactoryResetRequest: Asks peers to factory-reset.
FirmwareType: A firmware component.
FirmwareVersion: A firmware component reported by a device.
IrCapture: Raw IR captured on a bay of the sending device.
IrMeta: The raw-IR metadata shared by the IR capture and transmit frames.
IrTransmitRequest: Asks one device to blast raw IR on one of its local bays.
KeyTransmitRequest: Asks one device to send a remote-control key on a bay.
LinkFeature: Media carried by a virtual link.
MacAddress: A hardware address.
MultiviewerAspectRatio: The aspect ratio a multiviewer scales its windows to.
MultiviewerBool: A multiviewer setting that is on, off, or not reported.
MultiviewerCommand: A command addressed to a multiviewer.
MultiviewerEdidTemplate: The EDID template a multiviewer presents to its sources.
MultiviewerHdcpMode: The HDCP version a multiviewer output negotiates.
MultiviewerItcMode: The IT-content flag a multiviewer sets on its output.
MultiviewerOutputMode: The resolution and refresh rate a multiviewer drives its output at.
MultiviewerPipPosition: The corner a multiviewer places its picture-in-picture window in.
MultiviewerPipSize: The size of a multiviewer’s picture-in-picture window.
MultiviewerSource: One of a multiviewer’s four inputs.
MultiviewerStatus: A multiviewer’s complete reported state.
MultiviewerViewMode: The window layout of a multiviewer.
MuteStatus: The per-channel mute bitfield: bit 0 is left, bit 1 is right.
MxrSignalType: The 2-byte mxr_signal_type carried in scaling configs and bay signal reports.
NetworkPortStatus: The link state and diagnostics of a network port.
PduState: The electrical state a PDU reports.
RcAction: A remote-control action.
RcKey: A remote-control key code (CEC or IR).
RcSettings: The remote-control configuration of a source bay.
RcType: The remote-control protocol of a connected sink or source.
RebootRequest: Asks one device to reboot.
Remote: A client on the MX Remote network.
SetRouteRequest: Asks a device, addressed by serial, to switch a sink.
Svd: A Short Video Descriptor: one standard video resolution and timing.
TopologyEntry: One device in a topology report.
UidParseError: A UID could not be read from the given text or bytes.
UtpCableStatus: The diagnostic status of a single UTP cable pair.
UtpLinkErrors: The decoded link-error bitmask for a network port.
UtpLinkSpeed: The negotiated speed of a network port.
V2ipAudioFormat: Overrides the sample rate and channel count of a V2IP audio stream.
V2ipBlacklistChange: Registers or unregisters a device on the source blacklist.
V2ipDecoderState: The health state of a V2IP decoder.
V2ipDeviceStats: The cumulative and per-minute transmit and receive statistics.
V2ipDscpConfig: The per-stream DSCP marking in a V2IP device configuration.
V2ipPowerSaveRequest: Asks a sink to enter or leave power save.
V2ipRxStats: Receiver stream statistics.
V2ipScalingSettings: A V2IP output’s scaling mode, refresh rate and flags.
V2ipStreamSource: A single multicast stream address.
V2ipStreamSources: The streams advertised by a single V2IP source.
V2ipTilingConfig: The window a sink is currently told to show.
V2ipTxStats: Transmitter stream statistics.
VideoWallCommand: Asks one sink to crop its source to a wall window.
VideoWallOp: What a VideoWallCommand asks the sink to do with the window.
VolumeMuteStatus: The volume and mute state of a bay.

Enums§

ArcStatus: The audio return channel a bay is carrying.
ConnectStatus: The connect / signal-detect state reported for a bay.
ControlError: Why a control method did nothing.
DeviceStatus: The high-level state of a device or bay on the network.
Event: Something that changed, or a request that arrived.
HiddenStatus: The visibility state of a bay.
PowerStatus: The CEC power state of a device connected to a bay.
SendError: Why a frame was not sent.
StreamKind: Which of a V2IP device’s streams an address describes.
VctStatus: The result of a virtual cable test on one pair.

Constants§

AMP_EQ_BANDS: Number of EQ bands a zone carries (AMP_DOLBYEQBANDS_MAX).
AMP_TONE_FLAT: The neutral value for bass, treble and the EQ bands.
AMP_TONE_HTTP_MAX: Highest tone value the amp’s own HTTP API accepts. See AMP_TONE_HTTP_MIN.
AMP_TONE_HTTP_MIN: Lowest tone value the amp’s own HTTP API accepts.
BROADCAST_PORT: UDP port used in broadcast mode.
MULTICAST_IP: Multicast group address used for discovery.
MULTICAST_PORT: UDP port used in multicast mode.
MULTIVIEWER_INPUTS: How many windows a multiviewer can show, and how many sources it maps.
PROTOCOL_VERSION: Highest MX Remote protocol version understood.
SCALING_FLAGS_DEFINED: The flag bits that carry meaning.
SCALING_FLAG_AUTO_SCALING: Set when the output scales automatically.
SCALING_FLAG_MODE_VALID: Set when the frame carries a scaling mode and refresh rate.
SCALING_FLAG_OPTIONS_VALID: Set when the frame carries the scaling options.
V2IP_AUDIO_DEFAULT_CHANNELS: Channel count a V2IP audio stream uses when none is given.
V2IP_AUDIO_DEFAULT_SAMPLE_RATE: Sample rate a V2IP audio stream uses when none is given.
V2IP_AUDIO_MAX_CHANNELS: Highest channel count a V2IP audio stream accepts.
V2IP_AUDIO_MIN_CHANNELS: Lowest channel count a V2IP audio stream accepts.
V2IP_DSCP_DEFAULT: CS2, the marking the video processor applies at boot and the value firmware falls back to when a peer sends none.
V2IP_DSCP_MAX: Highest DSCP value; the marking occupies the upper 6 bits of the IPv4 TOS byte.
V2IP_DSCP_SET: Marks a DSCP byte as carrying a value.
V2IP_PORT_ANC: Default destination UDP port of a V2IP ancillary-data stream.
V2IP_PORT_AUDIO: Default destination UDP port of a V2IP audio stream.
V2IP_PORT_VIDEO: Default destination UDP port of a V2IP video stream.
V2IP_SOURCE_RATE_MAX: Highest valid encoder TX rate, in units of 10Mb/s. See V2IP_SOURCE_RATE_MIN.
V2IP_SOURCE_RATE_MIN: Lowest valid encoder TX rate, in units of 10Mb/s.
VERSION: Version of this library.

Traits§

EventHandler: Receives events.

Functions§

lookup_svd: Looks up the Short Video Descriptor with the given id.
valid_addresses: The non-loopback IPv4 addresses that can be used as a local address.

Crate mx_remote

Crate mx_remote Copy item path

§Getting started

§Events say what moved

§Values arrive as they were sent

§Threads

Structs§

Enums§

Constants§

Traits§

Functions§

Crate mx_remote