Crate mx_remote

Expand description

Client library for Pulse-Eight MatrixOS devices (neo matrices, OneIP 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.
BayAudioDetails: The audio a bay signal report describes.
BayContentField: One thing an input’s source is showing, such as its channel name.
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 OneIP device.
DeviceV2ipSink: The sink-side route a OneIP device is subscribed to, as the mesh believes it.
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 every unit, or one, 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.
OsdCaption: A caption, as a setting gives it.
OsdCaptionAlign: How a caption’s lines are aligned.
OsdCaptionField: The caption fields an overlay setting gives. A field left out keeps what the unit has.
OsdCaptionFormat: How a caption’s text is read.
OsdLogo: A logo choice and place, as a setting gives it.
OsdLogoField: The logo fields an overlay setting gives. A field left out keeps what the unit has.
OsdMessage: The message on a unit’s output, as the unit last reported it.
OsdMessageFlag: What a unit says of the message on its output.
OsdMessagePriority: Where a message stands against the unit’s own messages: its upgrade, Locate Device and encrypted source messages.
OsdSync: A sync, as its source sent it.
OsdSyncContent: What this client has units copy.
OsdSyncEntry: One setting of a sync this client sends.
OsdSyncImage: The logo image for one slot.
OsdSyncReport: How a unit is getting on with a sync.
OsdSyncRequest: A unit asking for a sync, or for settings of one it is taking, or management asking for a new sync for a unit.
OsdSyncSetting: One setting of a sync, which its source sends to one unit.
OsdSyncSize: The output size an overlay setting applies at.
OsdSyncSlot: One logo slot, as a sync describes it.
OsdSyncState: How far a unit has got with taking an overlay sync.
OsdSyncWhat: The kinds of overlay setting an overlay sync copies.
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 every unit, or one, 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.
TimeZone: The time zone a device announces for its mesh.
TopologyEntry: One device a unit found behind its switch ports, in its topology report.
UidParseError: A UID could not be read from the given text or bytes.
UnitCommand: A command for one unit, as a peer sent it.
UnitCommandFlag: The flags of a unit command.
UnitCommandKind: What a unit command asks of its unit.
UnitFlag: The flags of a unit’s status report.
UnitNetConfig: An IP configuration: the addresses a unit uses, or is told to use.
UnitPowerSave: What a unit offers at one power save level.
UnitStatus: A unit’s health and IP configuration, as it last reported them.
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: The sample rate and channel count a OneIP audio stream is decoded at.
V2ipBlacklistChange: Adds multicast groups to, or removes them from, the mesh-wide list that automatic address assignment avoids.
V2ipColourSpace: The colour space a OneIP output scales to.
V2ipDecoderFormat: The colour space a decoder recovered from a codestream.
V2ipDecoderReason: Why a decoder reports the state it does.
V2ipDecoderReport: What a sink’s decoder recovered from the codestream it is being given.
V2ipDecoderState: The health state of a OneIP decoder.
V2ipDeviceSetting: The device settings a OneIP configuration can carry, each on its own bit.
V2ipDeviceSettings: The device settings of a OneIP unit, as it reports them and as its controller changes them.
V2ipDeviceStats: The cumulative and per-minute transmit and receive statistics.
V2ipDownmix: How a OneIP output mixes 5.1 and 7.1 PCM down to stereo, and whether it does now.
V2ipDownmixLevel: How loud a OneIP output’s stereo downmix is.
V2ipDownmixMode: When a OneIP output mixes 5.1 and 7.1 PCM down to stereo.
V2ipDscpConfig: The per-stream DSCP marking in a OneIP device configuration.
V2ipFpgaFeature: What a OneIP device’s video processor supports, as the device reports it in its configuration.
V2ipOutputMode: The output format to scale a OneIP sink to.
V2ipPowerSaveLevel: How far a OneIP device powers down in power save, each level saving more than the one before.
V2ipPowerSaveRequest: Asks a sink to enter or leave power save.
V2ipPowerSaveSchedule: A OneIP device’s daily power save windows, Monday first, in the device’s time zone.
V2ipPrivacy: How a OneIP source unit’s streams are encrypted, as it last reported it.
V2ipPrivacyStream: How one of a OneIP source unit’s streams is encrypted, as the unit reports it: the values of the stream’s a=privacy and a=extmap session description attributes.
V2ipPtpFlag: The flags of a OneIP device’s PTP state.
V2ipPtpLock: How far a OneIP device’s PTP clock has locked to its master.
V2ipPtpMessages: How a OneIP device paces its PTP messages, its SAP timings, its streams’ TTL and its output’s rotation, which a frame carries in the same block. Each value is behind its own bit of V2ipDeviceSettings::valid, one of SETTINGS_BLOCK.
V2ipPtpMode: How a OneIP device takes part in PTP.
V2ipPtpState: A OneIP device’s PTP state, as it reports it about itself.
V2ipRoute: The three streams a manual route points a OneIP sink at.
V2ipRouteTarget: One multicast destination in a route the caller assembles.
V2ipRxStats: Receiver stream statistics.
V2ipScalingSettings: A OneIP output’s scaling mode, refresh rate and flags.
V2ipSdpClockMode: What a OneIP output’s video processor times a described stream by.
V2ipSdpClockState: How far a OneIP output’s video processor has got with a described stream’s timing.
V2ipSdpEncoding: The sample encoding of a stream a OneIP output plays from a description.
V2ipSdpFlag: The flags of what a OneIP output plays from a session description.
V2ipSdpMediaClock: Where a described stream’s media clock comes from.
V2ipSdpRefClock: The reference clock a described stream names.
V2ipSinkSdp: What a OneIP output plays from a session description, as it last reported it. The stream’s fields are zero while it plays none.
V2ipStreamSource: A single multicast stream address.
V2ipStreamSources: The streams advertised by a single OneIP source.
V2ipTestPattern: The test pattern a OneIP sink draws on its output.
V2ipTestSync: A OneIP sink’s lip-sync flash: a pattern frame is marked every period, the frame lead after a mark flashes white, and a BEEP tone starts offset sample periods after it.
V2ipTestTone: A OneIP sink’s test tone.
V2ipTestcard: The test card a OneIP sink draws on its output, as it last reported it.
V2ipTestcardFlag: What a OneIP sink reports about its test card.
V2ipTilingConfig: The window a sink is currently told to show.
V2ipToneMode: The test tone a OneIP sink plays on its output.
V2ipTxStats: Transmitter stream statistics.
V2ipVlan: VLAN tagging on a OneIP device’s uplink.
V2ipVlanFlag: The flags of a OneIP device’s VLAN configuration.
VideoWallCommand: Asks one sink to crop its source to a wall window.
VideoWallOp: What a VideoWallCommand asks the sink to do with the window.
VideoWallWindow: Where a video-wall sink’s window sits, and the picture it was measured against.
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.
OsdSyncValue: What one setting of a sync sets.
PowerStatus: The CEC power state of a device connected to a bay.
SendError: Why a frame was not sent.
StreamKind: Which of a OneIP device’s streams an address describes.
V2ipDecoderDetail: What a statistics report says about the sink’s decoder.
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.
BAY_CONTENT_KEY_MAX: The most bytes in a BayContentField::key.
BAY_CONTENT_VALUE_MAX: The most bytes in a BayContentField::value.
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.
OSD_MESSAGE_TEXT_MAX: The longest message text a unit takes, in bytes.
OSD_SYNC_FONT_MAX: The longest caption font name, in bytes.
OSD_SYNC_IMAGE_HEIGHT_MAX: See OSD_SYNC_IMAGE_WIDTH_MAX.
OSD_SYNC_IMAGE_MAX: The largest logo image a unit takes, in bytes.
OSD_SYNC_IMAGE_WIDTH_MAX: The widest and tallest logo image a unit takes, in pixels.
OSD_SYNC_PERCENT_MAX: The largest size a logo is shown at, in percent.
OSD_SYNC_RECORDS_MAX: The most settings one sync carries.
OSD_SYNC_SLOTS: The logo slots a sync can copy.
OSD_SYNC_TEXT_MAX: The longest caption text a unit shows, in bytes. It cuts a longer one short.
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_MATCH_SOURCE: Set when the output follows its source’s format instead of a fixed one.
SCALING_FLAG_MODE_VALID: Set when the frame carries a scaling mode and refresh rate.
SCALING_FLAG_OPTIONS2_VALID: Set when the frame carries the second group of scaling options.
SCALING_FLAG_OPTIONS_VALID: Set when the frame carries the scaling options.
SCALING_FLAG_SKIP_420: Set when the output declines 4:2:0 rather than scaling it.
TIME_ZONE_NAME_LEN: Bytes a time zone’s IANA name takes on the wire, its terminating NUL included.
TIME_ZONE_RULE_LEN: Bytes a time zone’s POSIX rule takes on the wire, its terminating NUL included.
UNIT_MAX_TEMPERATURES: The most temperature sensors a unit reports.
UNIT_POWER_SAVE_LEVELS: The power save levels a unit reports what it offers at, from REDUCED up.
V2IP_AUDIO_DEFAULT_CHANNELS: Channel count a OneIP audio stream uses when none is given.
V2IP_AUDIO_DEFAULT_SAMPLE_RATE: Sample rate a OneIP audio stream uses when none is given.
V2IP_AUDIO_MAX_CHANNELS: Highest channel count a OneIP audio stream accepts.
V2IP_AUDIO_MIN_CHANNELS: Lowest channel count a OneIP audio stream accepts.
V2IP_DOWNMIX_LFE_MAX: The largest percent a OneIP output mixes its LFE channel in at.
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_IR_PROFILE_MAX: One past the highest infrared profile: the default profile is 0, the Atlona profile 1, and user-defined profiles 1 to 16 are 2 to 17.
V2IP_IR_PROFILE_NOT_SET: The infrared profile an output’s port reports when it follows the device’s global one.
V2IP_MINUTES_PER_DAY: Minutes in a day: every time in a V2ipPowerSaveSchedule is below this.
V2IP_PORT_ANC: Default destination UDP port of a OneIP ancillary-data stream.
V2IP_PORT_AUDIO: Default destination UDP port of a OneIP audio stream.
V2IP_PORT_VIDEO: Default destination UDP port of a OneIP video stream.
V2IP_PTP_DOMAIN_MAX: The highest PTP domain a OneIP device runs in.
V2IP_SCALING_REFRESH_MAX: Highest refresh rate a OneIP output stage accepts, in Hz. See V2IP_SCALING_REFRESH_MIN.
V2IP_SCALING_REFRESH_MIN: Lowest refresh rate a OneIP output stage accepts, in Hz.
V2IP_SDP_MAX: The longest session description a OneIP output takes, in bytes.
V2IP_SINK_ROTATION_MAX: The largest angle a OneIP device’s HDMI output is turned by, in degrees.
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.
V2IP_STREAM_TTL_DEFAULT: The TTL a OneIP device’s streams carry until it is set.
V2IP_SYNC_BEEP_MS_MAX: The longest lip-sync beep, in milliseconds.
V2IP_SYNC_BEEP_MS_MIN: The shortest lip-sync beep, in milliseconds.
V2IP_SYNC_OFFSET_MAX: The largest lip-sync beep offset, in sample periods.
V2IP_TONE_CHANNELS_MAX: The most channels a test tone plays on.
V2IP_TONE_FREQ_MAX: The highest test tone frequency, in Hz.
V2IP_TONE_FREQ_MIN: The lowest test tone frequency, in Hz.
V2IP_TONE_LEVEL_MIN: The quietest test tone level, in dBFS; the loudest is 0.
V2IP_TONE_RATES: The sample rates a test tone plays at, in Hz.
V2IP_VLAN_ID_MAX: The highest VLAN id: 0 means untagged, and 4095 is reserved by IEEE 802.1Q.
V2IP_VLAN_PORTS: The external network ports a V2ipVlan covers, in the order of V2ipVlan::port: the SFP port, the UTP port with PoE, then the UTP port.
V2IP_VLAN_PORT_SFP: The index of the SFP port in V2ipVlan::port.
VERSION: Version of this library.
VIDEO_WALL_CLEARED: The window that clears a wall, leaving the sink showing the whole frame.
VIDEO_WALL_MIN_SIZE: Neither side of a window may be smaller than this, the scaler’s minimum.
VIDEO_WALL_POS_ALIGN: The horizontal origin must be a multiple of this: the sink’s buffer start has to be aligned.
VIDEO_WALL_WIDTH_ALIGN: The width must be a multiple of this: the sink’s pipeline moves four pixels per clock.
VOLUME_UNCHANGED: The value that means “leave this one alone” in a volume or mute field.

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