mx_remote/runtime/

control.rs

// Author: Lars Op den Kamp (lars@opdenkamp-it.nl)
// Copyright (c) 2026 Op den Kamp IT Solutions

//! The control surface: what a caller can ask a device to do.
//!
//! Every method here has the same shape. It reads the registry to decide what
//! to send, releases that lock, transmits, and only then writes back what the
//! device will have done. The order is what makes a handler woken by the
//! write-back free to call in again, and it keeps the receive thread from
//! waiting on a socket write for the lock it needs to decode.
//!
//! Nothing here reaches the wire on its own: a payload is bytes until the
//! single transmit path stamps and writes it, which is where the addressee's
//! protocol version is checked.
//!
//! The multiviewer and audio-endpoint methods are served by loadable modules
//! rather than by the device firmware, and a model may not load modules at
//! all, may not ship that one, or may not support it. Those modules answer
//! nothing either way, so an `Ok` from one of those methods says a frame left
//! the socket and no more: "the device did it" and "nothing on the device
//! handles this" are the same observation from here. Read the state back to
//! tell them apart. A multiviewer broadcasts its whole status shortly after a
//! setting it accepted, which serves as that read for every one of its methods
//! but [`Remote::set_multiviewer_remote_control`] and
//! [`Remote::set_multiviewer_input_source`], which broadcast nothing.

use std::fmt;
use std::net::Ipv4Addr;
use std::time::{SystemTime, UNIX_EPOCH};

use crate::event::Event;
use crate::state::{Bay, Device, State};
use crate::types::{
    AmpZoneSettings, AudioFeatures, HiddenStatus, MultiviewerStatus, PowerStatus, ThirdPartyVendor,
    UnitNetConfig, V2ipAudioFormat, V2ipDeviceSettings, V2ipDownmix, V2ipOutputMode,
    V2ipPowerSaveSchedule, V2ipPtpMessages, V2ipRoute, V2ipRouteTarget, V2ipScalingSettings,
    V2ipStreamSources, V2ipTestSync, V2ipTestTone, V2ipTestcard, V2ipVlan, VideoWallOp,
    VideoWallWindow, VolumeMuteStatus, MULTIVIEWER_INPUTS, OSD_MESSAGE_TEXT_MAX,
    SCALING_FLAG_AUTO_SCALING, SCALING_FLAG_MODE_VALID, SCALING_FLAG_OPTIONS_VALID,
    THIRD_PARTY_PAYLOAD_MAX, V2IP_PTP_DOMAIN_MAX, V2IP_SDP_MAX, V2IP_SINK_ROTATION_MAX,
    V2IP_VLAN_PORT_SFP, VIDEO_WALL_CLEARED,
};
use crate::wire::{
    audio_cmd_header, audio_param, audio_sub, build_amp_zone_settings, build_audio_select_input,
    build_bay_hide, build_edid_profile, build_edid_request, build_mesh_operation,
    build_osd_message, build_privacy_request, build_rc_action, build_rc_key, build_set_bay_name,
    build_set_volume, build_sink_sdp_command, build_sink_sdp_pages, build_stats_request,
    build_target_only, build_third_party, build_time_zone, build_unit_command,
    build_v2ip_device_settings, build_v2ip_downmix, build_v2ip_manual_source_switch,
    build_v2ip_scaling, build_v2ip_settings_all, build_v2ip_source_switch, build_v2ip_testcard,
    build_v2ip_vlan, build_video_wall, mesh_op, mv_cmd_payload, mv_sub, op, osd_kind, sdp_type,
    testcard_part, testcard_type, Addressee, BayUid, DeviceFeature, DeviceUid, EdidProfile,
    MultiviewerAspectRatio, MultiviewerEdidTemplate, MultiviewerHdcpMode, MultiviewerItcMode,
    MultiviewerOutputMode, MultiviewerPipPosition, MultiviewerPipSize, MultiviewerSource,
    MultiviewerViewMode, MxrSignalType, Opcode, OsdMessageFlag, OsdMessagePriority, RcAction,
    RcKey, SendError, StreamAddr, UnitCommandFlag, UnitCommandKind, UnitFlag, V2ipDeviceSetting,
    V2ipFpgaFeature, V2ipPowerSaveLevel, V2ipPtpMode, V2ipStreams, V2ipTestPattern, V2ipToneMode,
    V2ipVlanFlag, DEVICE_NAME_LEN, TIME_ZONE_NAME_LEN, TIME_ZONE_RULE_LEN, V2IP_DSCP_MAX,
    V2IP_IR_PROFILE_MAX, V2IP_IR_PROFILE_NOT_SET, V2IP_PORT_ANC, V2IP_PORT_AUDIO, V2IP_PORT_VIDEO,
};

use super::{Remote, Shared};

/// Why a control method did nothing.
#[derive(Debug)]
#[non_exhaustive]
pub enum ControlError {
    /// No device with this identifier has been heard from.
    UnknownDevice(DeviceUid),
    /// The device has reported no bay on this port.
    UnknownBay(BayUid),
    /// No input bay on the device carries this user-assigned name.
    UnknownSource(String),
    /// The addressee does not do what was asked of it.
    Unsupported(&'static str),
    /// The request breaks a rule the device is not guaranteed to check.
    ///
    /// Nothing was sent. This is the caller's to fix, and it is separate from
    /// [`ControlError::Unsupported`] because the device would have taken the
    /// frame: refusing here is this library declining to let a bad value
    /// reach hardware that may store it rather than reject it.
    InvalidRequest(&'static str),
    /// The device has not reported something the request is assembled from.
    ///
    /// Unlike [`ControlError::Unsupported`], the same call may succeed once it
    /// has: this says the value is missing, not that it cannot exist.
    NotReported(&'static str),
    /// The frame could not be sent.
    Send(SendError),
}

impl fmt::Display for ControlError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::UnknownDevice(uid) => write!(f, "no device {uid}"),
            Self::UnknownBay(uid) => write!(f, "no bay {uid}"),
            Self::UnknownSource(name) => write!(f, "no source named {name:?}"),
            Self::Unsupported(what) => f.write_str(what),
            Self::InvalidRequest(what) => f.write_str(what),
            Self::NotReported(what) => write!(f, "{what} has not been reported"),
            Self::Send(e) => write!(f, "{e}"),
        }
    }
}

impl std::error::Error for ControlError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Send(e) => Some(e),
            _ => None,
        }
    }
}

impl From<SendError> for ControlError {
    fn from(e: SendError) -> Self {
        Self::Send(e)
    }
}

/// What a command does to this client's copy of the registry once its frame is
/// away.
///
/// A device does not acknowledge a command, so without this a caller that read
/// back what it just wrote would see the old value until some unrelated report
/// happened to carry the new one.
type WriteBack = Box<dyn FnOnce(&mut State, &mut Vec<Event>) + Send>;

/// One command: the frame to send, and what the addressee will do with it.
struct Command {
    to: Addressee,
    opcode: Opcode,
    payload: Vec<u8>,
    write_back: Option<WriteBack>,
}

impl Command {
    fn new(to: Addressee, opcode: Opcode, payload: Vec<u8>) -> Self {
        Self {
            to,
            opcode,
            payload,
            write_back: None,
        }
    }

    /// Records what to apply locally once the frame is away.
    fn then(mut self, f: impl FnOnce(&mut State, &mut Vec<Event>) + Send + 'static) -> Self {
        self.write_back = Some(Box::new(f));
        self
    }
}

impl Shared {
    /// Runs one command: prepare under the registry lock, send without it,
    /// then write back.
    fn command(
        &self,
        prepare: impl FnOnce(&State) -> Result<Command, ControlError>,
    ) -> Result<(), ControlError> {
        let command = self.read(prepare)?;
        self.send(&command.to, command.opcode, &command.payload)?;
        if let Some(write_back) = command.write_back {
            self.mutate(|state, ev| write_back(state, ev));
        }
        Ok(())
    }
}

/// The first protocol version whose devices can act on the automatic address
/// operation.
///
/// Not the stamp: that is the mesh operation opcode's, and a device between
/// the two takes the frame and ignores an operation it does not know. Not
/// every device on this version has it either, but none below it does.
const AUTO_ADDRESSES_PROTOCOL: u16 = 0x2B;

/// The first protocol version whose outputs report the session description
/// they play.
///
/// Not the stamp: that is the session description opcode's, and an output
/// between the two answers the request with its status alone.
const SDP_DESCRIPTION_PROTOCOL: u16 = 0x31;

/// The bit of a session description request's value that asks for the
/// description too.
const SDP_REQUEST_DESCRIPTION: u8 = 1 << 0;

fn device_of(state: &State, uid: DeviceUid) -> Result<&Device, ControlError> {
    state.device(uid).ok_or(ControlError::UnknownDevice(uid))
}

/// The device behind `uid`, once it is known to be a OneIP output.
fn sdp_sink_of(state: &State, uid: DeviceUid) -> Result<&Device, ControlError> {
    let device = device_of(state, uid)?;
    if !device.is_v2ip_sink() {
        return Err(ControlError::Unsupported(
            "the device is not a OneIP output",
        ));
    }
    Ok(device)
}

/// A unit command for the unit behind `uid`, once it is known to be a OneIP
/// unit.
fn unit_command_of(
    state: &State,
    uid: DeviceUid,
    command: UnitCommandKind,
    flags: UnitCommandFlag,
    network: Option<UnitNetConfig>,
) -> Result<Command, ControlError> {
    let d = device_of(state, uid)?;
    if !d.is_v2ip() {
        return Err(ControlError::Unsupported("the device is not a OneIP unit"));
    }
    Ok(Command::new(
        Addressee::device(d),
        op::SYS_UNIT_COMMAND,
        build_unit_command(d.uid, command, flags, network.as_ref()),
    ))
}

/// The device behind `uid`, once it is known to be a multiviewer.
fn multiviewer_of(state: &State, uid: DeviceUid) -> Result<&Device, ControlError> {
    let device = device_of(state, uid)?;
    if !device.is_multiviewer() {
        return Err(ControlError::Unsupported("the device is not a multiviewer"));
    }
    Ok(device)
}

/// Wraps one multiviewer sub-command in the envelope every one of them shares.
fn mv_command(device: &Device, sub: u8, args: &[u8]) -> Command {
    Command::new(
        Addressee::device(device),
        op::V2IP_MULTIVIEWER,
        mv_cmd_payload(device.uid, sub, args),
    )
}

/// The zero-based input a source names, refused when it names none.
///
/// A multiviewer reads zero as its first input, so there is no value that says
/// "no input": a source that names none would arrive as a request to switch to
/// input 1.
fn source_index(source: MultiviewerSource, what: &'static str) -> Result<u8, ControlError> {
    source
        .to_zero_based()
        .ok_or(ControlError::InvalidRequest(what))
}

/// A multiviewer setting within the range its firmware accepts.
///
/// Every one of these settings is numbered from one, with zero reserved for
/// "the device has reported nothing". The device drops a value it does not
/// know without answering, so a caller sending one would see a send succeed
/// and the setting stay as it was; this is what turns that into an error.
fn mv_setting(value: u8, highest: u8, what: &'static str) -> Result<u8, ControlError> {
    if (1..=highest).contains(&value) {
        Ok(value)
    } else {
        Err(ControlError::InvalidRequest(what))
    }
}

fn bay_of(state: &State, uid: BayUid) -> Result<(&Device, &Bay), ControlError> {
    let device = device_of(state, uid.device)?;
    let bay = device.bay(uid.port).ok_or(ControlError::UnknownBay(uid))?;
    Ok((device, bay))
}

/// The bay a command about `uid` acts on, and its device.
///
/// A mesh bay stands for bay 0 of another unit, which holds everything the
/// mesh bay reports, so a command goes to that unit about that bay. Until
/// the unit has reported the bay there is nowhere to send it, and it is
/// refused.
fn acted_on(state: &State, uid: BayUid) -> Result<(&Device, &Bay), ControlError> {
    let (device, bay) = bay_of(state, uid)?;
    if !bay.is_v2ip_remote() {
        return Ok((device, bay));
    }
    let owner = state
        .mesh_owner(bay)
        .ok_or(ControlError::NotReported("the bay the mesh bay stands for"))?;
    Ok((device_of(state, owner.uid().device)?, owner))
}

/// The streams the source bay on `port` advertises.
fn source_streams(device: &Device, port: u16) -> Result<&V2ipStreamSources, ControlError> {
    let source = device
        .bay(port)
        .ok_or(ControlError::UnknownBay(BayUid::new(device.uid, port)))?;
    device
        .v2ip_source_for(source)
        .ok_or(ControlError::NotReported("the source's stream addresses"))
}

/// A sink bay, or the reason it cannot be routed.
///
/// Returns the device listing the sink, whose numbering the source ports of
/// a route are in, then the unit and bay that play the route.
fn v2ip_sink(state: &State, uid: BayUid) -> Result<(&Device, &Device, &Bay), ControlError> {
    let (_, bay) = bay_of(state, uid)?;
    if !bay.is_v2ip_sink() {
        return Err(ControlError::Unsupported("routing needs a OneIP sink"));
    }
    let (unit, sink) = acted_on(state, uid)?;
    Ok((device_of(state, uid.device)?, unit, sink))
}

/// One route slot as the wire carries it, substituting the stream's standard
/// port for an unset one.
///
/// An unset address sends the slot zeroed, port included: the firmware reads
/// the pair together, and a port beside 0.0.0.0 describes nothing.
fn stream_addr(target: V2ipRouteTarget, standard_port: u16) -> StreamAddr {
    if target.ip.is_unspecified() {
        return StreamAddr::default();
    }
    StreamAddr {
        ip: target.ip,
        port: target.port_or(standard_port),
    }
}

/// The protocol from which every unit's audio follows its video for a source
/// switch naming no audio. Some units below it route no audio instead.
const AUDIO_FOLLOWS_SINCE: u16 = 0x27;

/// The protocol of the earliest firmware known to carry the current audio
/// module layout; a unit below it that has not reported its endpoints is
/// taken to carry the older one.
const AUDIO_LAYOUT_SINCE: u16 = 0x27;

/// The protocol from which a unit applies a scaling write from management.
const SCALING_WRITE_PROTOCOL: u16 = 0x2F;

/// The name as the device will store it. A unit keeps 15 bytes of the
/// [`DEVICE_NAME_LEN`]-byte field, the last being its terminator, so a longer
/// name is cut there, before any character that would not fit whole.
fn stored_name(name: &str) -> String {
    let mut end = name.len().min(DEVICE_NAME_LEN - 1);
    while !name.is_char_boundary(end) {
        end -= 1;
    }
    name[..end].to_owned()
}

impl Remote {
    // ---- routing ----

    /// Routes this OneIP sink's video to the stream a source port advertises.
    ///
    /// The sink's audio then follows the video: a separate audio route is
    /// dropped, so route audio after video to keep them apart. A unit below
    /// protocol 0x27 is routed the source's audio stream instead, as some of
    /// those route no audio for "follow the video".
    pub fn select_video_source(&self, sink: BayUid, source_port: u16) -> Result<(), ControlError> {
        self.shared.command(|state| {
            let (listing, device, bay) = v2ip_sink(state, sink)?;
            if !bay.is_output() {
                return Err(ControlError::Unsupported("not an output bay"));
            }
            let streams = source_streams(listing, source_port)?;
            // Older firmware routes no audio for an empty audio address rather
            // than following the video, so it is told the source's audio
            // stream instead, which every version plays.
            let audio = if device.hello.supported_protocol < AUDIO_FOLLOWS_SINCE {
                streams.audio.ip
            } else {
                Ipv4Addr::UNSPECIFIED
            };
            Ok(Command::new(
                Addressee::device(device),
                op::V2IP_SOURCE_SWITCH,
                build_v2ip_source_switch(device.uid, streams.video.ip, audio),
            ))
        })
    }

    /// Routes this OneIP sink's audio to the stream a source port advertises.
    pub fn select_audio_source(&self, sink: BayUid, source_port: u16) -> Result<(), ControlError> {
        self.shared.command(|state| {
            let (listing, device, _) = v2ip_sink(state, sink)?;
            let streams = source_streams(listing, source_port)?;
            Ok(Command::new(
                Addressee::device(device),
                op::V2IP_SOURCE_SWITCH,
                build_v2ip_source_switch(device.uid, Ipv4Addr::UNSPECIFIED, streams.audio.ip),
            ))
        })
    }

    /// Routes this OneIP sink's video to the input bay with the given
    /// user-assigned name.
    pub fn select_video_source_by_name(
        &self,
        sink: BayUid,
        name: &str,
    ) -> Result<(), ControlError> {
        self.select_video_source(sink, self.source_port(sink, name)?)
    }

    /// Routes this OneIP sink's audio to a multicast address directly, leaving
    /// its video and ancillary streams alone.
    ///
    /// An unset port is the standard OneIP audio port. A format overrides the
    /// sample rate and channel count the receiver would otherwise assume.
    pub fn select_audio_source_addr(
        &self,
        sink: BayUid,
        audio_ip: Ipv4Addr,
        audio_port: Option<u16>,
        format: Option<V2ipAudioFormat>,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let (_, device, _) = v2ip_sink(state, sink)?;
            let streams = V2ipStreams {
                audio: StreamAddr {
                    ip: audio_ip,
                    port: audio_port.unwrap_or(V2IP_PORT_AUDIO),
                },
                ..V2ipStreams::default()
            };
            Ok(Command::new(
                Addressee::device(device),
                op::V2IP_MANUAL_SRC_SWITCH,
                build_v2ip_manual_source_switch(device.uid, streams, format),
            ))
        })
    }

    /// Routes this OneIP sink's video, audio and ancillary streams to
    /// multicast groups the caller names.
    ///
    /// This is the only way to reach a stream no device on the mesh
    /// advertises, such as one the host is transmitting itself; a route by
    /// source port can only name a stream some bay has announced.
    ///
    /// Set all three groups. The firmware decides whether a sink has a manual
    /// route by looking at the video and ancillary groups, so a route that
    /// leaves either unset does not register as one and the sink falls back to
    /// the audio source its mesh picks.
    ///
    /// An unset `format` sends [`V2ipAudioFormat::STANDARD`] rather than
    /// omitting the trailer. The firmware stores whatever this frame carries
    /// and hands it to the FPGA unexamined, so a frame without one leaves a
    /// zero rate and zero channel count there, which the FPGA rejects and
    /// which takes the switch down with it.
    pub fn select_source_addr(
        &self,
        sink: BayUid,
        route: V2ipRoute,
        format: Option<V2ipAudioFormat>,
    ) -> Result<(), ControlError> {
        let streams = V2ipStreams {
            video: stream_addr(route.video, V2IP_PORT_VIDEO),
            audio: stream_addr(route.audio, V2IP_PORT_AUDIO),
            anc: stream_addr(route.anc, V2IP_PORT_ANC),
        };
        let format = format.unwrap_or(V2ipAudioFormat::STANDARD);
        self.shared.command(move |state| {
            let (_, device, _) = v2ip_sink(state, sink)?;
            Ok(Command::new(
                Addressee::device(device),
                op::V2IP_MANUAL_SRC_SWITCH,
                build_v2ip_manual_source_switch(device.uid, streams, Some(format)),
            ))
        })
    }

    /// Routes this OneIP sink's audio from the input bay with the given
    /// user-assigned name.
    ///
    /// A format is carried on the manual switch frame, which is the only form
    /// that can override the receiver's sample rate and channel count.
    pub fn select_audio_source_by_name(
        &self,
        sink: BayUid,
        name: &str,
        format: Option<V2ipAudioFormat>,
    ) -> Result<(), ControlError> {
        let port = self.source_port(sink, name)?;
        let Some(format) = format else {
            return self.select_audio_source(sink, port);
        };
        self.shared.command(move |state| {
            let (listing, device, _) = v2ip_sink(state, sink)?;
            let audio = source_streams(listing, port)?.audio;
            let streams = V2ipStreams {
                audio: StreamAddr {
                    ip: audio.ip,
                    port: audio.port,
                },
                ..V2ipStreams::default()
            };
            Ok(Command::new(
                Addressee::device(device),
                op::V2IP_MANUAL_SRC_SWITCH,
                build_v2ip_manual_source_switch(device.uid, streams, Some(format)),
            ))
        })
    }

    /// The port of the input bay on `sink`'s device carrying `name`.
    fn source_port(&self, sink: BayUid, name: &str) -> Result<u16, ControlError> {
        self.shared.read(|state| {
            let (device, _) = bay_of(state, sink)?;
            state
                .input_by_user_name(device, name)
                .map(|b| b.port)
                .ok_or_else(|| ControlError::UnknownSource(name.to_owned()))
        })
    }

    // ---- bay settings ----

    /// Renames a bay.
    pub fn set_bay_name(&self, bay: BayUid, name: &str) -> Result<(), ControlError> {
        let name = stored_name(name);
        self.shared.command(move |state| {
            let (device, b) = acted_on(state, bay)?;
            let bay = b.uid();
            let payload = build_set_bay_name(device.uid, bay.port, &name);
            Ok(
                Command::new(Addressee::device(device), op::CHANGE_BAY_NAME, payload).then(
                    move |state, ev| {
                        if let Some(b) = state.bay_mut(bay) {
                            b.set_user_name(name, ev);
                        }
                    },
                ),
            )
        })
    }

    /// Hides a bay from the pickers that list it, or shows it again.
    pub fn set_bay_hidden(&self, bay: BayUid, hidden: bool) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let (device, b) = acted_on(state, bay)?;
            let bay = b.uid();
            Ok(Command::new(
                Addressee::device(device),
                op::BAY_HIDE,
                build_bay_hide(device.uid, bay.port, hidden),
            )
            .then(move |state, ev| {
                if let Some(b) = state.bay_mut(bay) {
                    let status = if hidden {
                        HiddenStatus::Hidden
                    } else {
                        HiddenStatus::Visible
                    };
                    b.apply_hidden(status, ev);
                }
            }))
        })
    }

    /// Sets the EDID profile an input presents to the source attached to it.
    pub fn select_edid_profile(
        &self,
        bay: BayUid,
        profile: EdidProfile,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let (device, b) = acted_on(state, bay)?;
            let bay = b.uid();
            Ok(Command::new(
                Addressee::device(device),
                op::BAY_EDID_PROFILE,
                build_edid_profile(device.uid, profile),
            )
            .then(move |state, ev| {
                if let Some(b) = state.bay_mut(bay) {
                    b.set_edid_profile(profile, ev);
                }
            }))
        })
    }

    /// Sends a remote-control action to whatever is attached to a bay.
    pub fn send_action(&self, bay: BayUid, action: RcAction) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let (device, b) = acted_on(state, bay)?;
            Ok(Command::new(
                Addressee::device(device),
                op::RC_TX_ACTION,
                build_rc_action(device.uid, b.port, action),
            ))
        })
    }

    /// Sends a remote-control key press to whatever is attached to a bay.
    ///
    /// The device forwards it over CEC, infrared or IP, whichever that bay is
    /// configured for; the caller does not choose. An action from
    /// [`Remote::send_action`] names an outcome instead, and the device
    /// decides which keys reach it.
    pub fn send_key(&self, bay: BayUid, key: RcKey) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let (device, b) = acted_on(state, bay)?;
            Ok(Command::new(
                Addressee::device(device),
                op::RC_TX_KEY,
                build_rc_key(device.uid, b.port, key),
            ))
        })
    }

    /// Powers on the device attached to a bay.
    pub fn power_on(&self, bay: BayUid) -> Result<(), ControlError> {
        self.set_power(bay, RcAction::POWER_ON, PowerStatus::On)
    }

    /// Powers off the device attached to a bay.
    pub fn power_off(&self, bay: BayUid) -> Result<(), ControlError> {
        self.set_power(bay, RcAction::POWER_OFF, PowerStatus::Off)
    }

    fn set_power(
        &self,
        bay: BayUid,
        action: RcAction,
        power: PowerStatus,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let (device, b) = acted_on(state, bay)?;
            let bay = b.uid();
            Ok(Command::new(
                Addressee::device(device),
                op::RC_TX_ACTION,
                build_rc_action(device.uid, bay.port, action),
            )
            .then(move |state, ev| {
                if let Some(b) = state.bay_mut(bay) {
                    b.set_power_status(power, ev);
                }
            }))
        })
    }

    /// Sets a bay's volume, as a percentage, and optionally its mute state.
    ///
    /// Both channels are set together: the wire carries them separately, but
    /// nothing on this surface splits them.
    ///
    /// A bay with no volume control of its own is set through its
    /// [`linked_bay`](crate::BayInfo::linked_bay), so an output wired to an
    /// amplifier zone reaches that zone. [`volume_up`](Self::volume_up),
    /// [`volume_down`](Self::volume_down) and [`set_muted`](Self::set_muted)
    /// follow the same link, and read the volume they step from through it.
    pub fn set_volume(
        &self,
        bay: BayUid,
        volume: u8,
        muted: Option<bool>,
    ) -> Result<(), ControlError> {
        let volume = volume.min(100);
        let wanted = VolumeMuteStatus {
            volume_left: Some(volume),
            volume_right: Some(volume),
            muted_left: muted,
            muted_right: muted,
        };
        self.shared.command(move |state| {
            // The mesh may put this bay's volume control on another device, and
            // the command belongs where the volume lives, not where it was
            // addressed.
            let target = state.volume_bay(acted_on(state, bay)?.1.uid());
            let (device, b) = bay_of(state, target)?;
            if !b.has_volume_control() {
                return Err(ControlError::Unsupported("the bay has no volume control"));
            }
            Ok(Command::new(
                Addressee::device(device),
                op::AUDIO_SET_VOLUME,
                build_set_volume(device.uid, target.port, wanted),
            )
            .then(move |state, ev| {
                if let Some(device) = state.device_mut(target.device) {
                    device.apply_bay_volume(target.port, wanted, ev);
                }
            }))
        })
    }

    /// Raises a bay's volume by one percent.
    ///
    /// The step carries the mute state the bay last reported rather than
    /// "unchanged", which an older matrix reads as mute.
    pub fn volume_up(&self, bay: BayUid) -> Result<(), ControlError> {
        let (volume, muted) = self.current_volume(bay)?;
        self.set_volume(bay, volume.saturating_add(1), muted)
    }

    /// Lowers a bay's volume by one percent, as [`Remote::volume_up`] does.
    pub fn volume_down(&self, bay: BayUid) -> Result<(), ControlError> {
        let (volume, muted) = self.current_volume(bay)?;
        self.set_volume(bay, volume.saturating_sub(1), muted)
    }

    /// Mutes or unmutes a bay, keeping the volume it is set to.
    pub fn set_muted(&self, bay: BayUid, muted: bool) -> Result<(), ControlError> {
        self.set_volume(bay, self.current_volume(bay)?.0, Some(muted))
    }

    /// The volume a step or a mute is relative to, and the mute state it
    /// keeps.
    fn current_volume(&self, bay: BayUid) -> Result<(u8, Option<bool>), ControlError> {
        self.shared.read(|state| {
            let (_, b) = bay_of(state, state.volume_bay(acted_on(state, bay)?.1.uid()))?;
            b.audio_volume
                .map(|v| (v.volume(), v.muted()))
                .ok_or(ControlError::NotReported("the bay's volume"))
        })
    }

    /// Applies amplifier settings to a zone.
    pub fn set_amp_zone_settings(
        &self,
        bay: BayUid,
        settings: AmpZoneSettings,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let (device, b) = acted_on(state, bay)?;
            let bay = b.uid();
            Ok(Command::new(
                Addressee::device(device),
                op::AMP_ZONE_SETTINGS,
                build_amp_zone_settings(device.uid, bay.port, &settings),
            )
            .then(move |state, ev| {
                if let Some(b) = state.bay_mut(bay) {
                    b.set_amp_settings(settings, ev);
                }
            }))
        })
    }

    // ---- audio endpoints ----

    /// Mutes or unmutes an audio endpoint.
    ///
    /// Refused unless the endpoint reports [`AudioFeatures::MUTE`]: a unit
    /// changes nothing for one that does not.
    pub fn set_audio_endpoint_muted(
        &self,
        device: DeviceUid,
        endpoint: u16,
        muted: bool,
    ) -> Result<(), ControlError> {
        self.featured_audio_endpoint(
            device,
            audio_sub::MUTE,
            endpoint,
            muted,
            AudioFeatures::MUTE,
        )
    }

    /// Sets an audio endpoint's trigger output.
    ///
    /// Refused unless the endpoint reports [`AudioFeatures::TRIGGER`]: a unit
    /// changes nothing for one that does not.
    pub fn set_audio_endpoint_trigger(
        &self,
        device: DeviceUid,
        endpoint: u16,
        active: bool,
    ) -> Result<(), ControlError> {
        self.featured_audio_endpoint(
            device,
            audio_sub::TRIGGER,
            endpoint,
            active,
            AudioFeatures::TRIGGER,
        )
    }

    /// Locks or unlocks the audio source of an audio endpoint: while it is
    /// locked, a video route change leaves the endpoint's audio source alone.
    ///
    /// Refused unless the endpoint reports
    /// [`AudioFeatures::AUDIO_LOCK`], which
    /// is the only one the device acts on. The device reports its endpoints
    /// again once the lock has changed;
    /// [`AudioEndpoints::status`](crate::AudioEndpoints::status) reads it.
    pub fn set_audio_endpoint_locked(
        &self,
        device: DeviceUid,
        endpoint: u8,
        locked: bool,
    ) -> Result<(), ControlError> {
        self.featured_audio_endpoint(
            device,
            audio_sub::LOCK,
            u16::from(endpoint),
            locked,
            AudioFeatures::AUDIO_LOCK,
        )
    }

    /// Sends an on/off endpoint command, refused unless the endpoint reports
    /// `feature`, the only case a unit acts on.
    fn featured_audio_endpoint(
        &self,
        device: DeviceUid,
        sub: u16,
        endpoint: u16,
        on: bool,
        feature: AudioFeatures,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            let Some(endpoints) = d.audio.as_ref() else {
                return Err(ControlError::NotReported("the device's audio endpoints"));
            };
            let id = u8::try_from(endpoint).ok();
            if !id
                .and_then(|id| endpoints.get(id))
                .is_some_and(|ep| ep.features.has(feature))
            {
                return Err(ControlError::Unsupported(
                    "the endpoint does not have that feature",
                ));
            }
            let mut payload = audio_cmd_header(sub, d.uid);
            payload.extend_from_slice(&audio_param(endpoint, u32::from(on)));
            Ok(Command::new(Addressee::device(d), op::V2IP_AUDIO, payload))
        })
    }

    /// Sets an audio endpoint's volume. Always refused.
    ///
    /// No unit acts on the command: the audio module defines it but neither
    /// sends nor handles it, and a unit on released firmware reads the same
    /// sub-opcode as a request to select an output.
    pub fn set_audio_endpoint_volume(
        &self,
        _device: DeviceUid,
        _endpoint: u16,
        _volume: u32,
    ) -> Result<(), ControlError> {
        Err(ControlError::Unsupported(
            "no unit acts on an endpoint volume",
        ))
    }

    /// Routes a source endpoint on one device to a sink endpoint on another.
    ///
    /// A unit on released firmware up to 4.4.2 routes only between its own
    /// endpoints, so a route from another unit to one is refused.
    pub fn select_audio_endpoint_input(
        &self,
        sink: DeviceUid,
        sink_endpoint: u16,
        source: DeviceUid,
        source_endpoint: u16,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let device = device_of(state, sink)?;
            // An audio module on released firmware up to 4.4.2 reads an
            // 8-byte body naming two of its own endpoints, and the current
            // one reads 36 bytes naming both units; neither checks the
            // length, so each is sent only its own.
            let payload = if device
                .audio_legacy
                .unwrap_or(device.hello.supported_protocol < AUDIO_LAYOUT_SINCE)
            {
                if source != sink {
                    return Err(ControlError::Unsupported(
                        "the unit routes only its own audio endpoints",
                    ));
                }
                let mut payload = audio_cmd_header(audio_sub::SELECT_INPUT, sink);
                payload.extend_from_slice(&audio_param(sink_endpoint, u32::from(source_endpoint)));
                payload
            } else {
                build_audio_select_input(sink, sink_endpoint, source, source_endpoint)
            };
            Ok(Command::new(
                Addressee::device(device),
                op::V2IP_AUDIO,
                payload,
            ))
        })
    }

    // ---- the whole device ----

    /// Starts or stops a OneIP device reporting its transport statistics.
    ///
    /// There is no free-running mode: a device reports only while a
    /// subscription is live, at 1Hz, and the subscription lapses after a
    /// minute. A caller that wants a continuous feed re-sends inside the
    /// minute; nothing here re-arms it.
    ///
    /// Reports reach [`crate::EventHandler::on_v2ip_stats_changed`] and read
    /// back through [`Remote::v2ip_stats`]. A device new enough to send it also
    /// carries what the sink's decoder recovered, in
    /// [`crate::V2ipDeviceStats::decoder`].
    pub fn subscribe_v2ip_stats(
        &self,
        device: DeviceUid,
        subscribe: bool,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let device = device_of(state, device)?;
            Ok(Command::new(
                Addressee::device(device),
                op::V2IP_STATS,
                build_stats_request(device.uid, subscribe),
            ))
        })
    }

    /// Asks a device for an EDID: the one the display on its output
    /// publishes, or the one it presents to the source on its input.
    ///
    /// The device answers with a frame the receive path decodes, so the bytes
    /// arrive at [`crate::EventHandler::on_edid_received`] and stay readable
    /// through [`Remote::edid`].
    ///
    /// Only OneIP hardware handles this opcode. A matrix or an amplifier
    /// accepts the frame and answers nothing, at any protocol version, so the
    /// silence that follows is permanent rather than a reply still to come.
    /// This call cannot tell the two apart and does not try: it reports what
    /// was sent, and a caller polling for an EDID should ask a device that can
    /// answer rather than wait on one that cannot.
    pub fn request_edid(&self, device: DeviceUid, output: bool) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let device = device_of(state, device)?;
            Ok(Command::new(
                Addressee::device(device),
                op::DEV_EDID,
                build_edid_request(device.uid, output),
            ))
        })
    }

    /// Asks for a detailed signal report from every bay of one device, or -
    /// with no device named - from every bay on the network.
    ///
    /// Devices report on their own when a signal changes, so this is what a
    /// client that has just started needs: without it, a bay that has been
    /// showing the same picture for an hour says nothing until it changes.
    pub fn request_signal_status(&self, device: Option<DeviceUid>) -> Result<(), ControlError> {
        let Some(device) = device else {
            self.shared
                .send(&Addressee::Broadcast, op::BAY_SIGNAL_STATUS, &[])?;
            return Ok(());
        };
        self.shared.command(move |state| {
            let device = device_of(state, device)?;
            Ok(Command::new(
                Addressee::device(device),
                op::BAY_SIGNAL_STATUS,
                build_target_only(device.uid),
            ))
        })
    }

    /// Reboots a device.
    ///
    /// The device is marked as rebooting once the frame is away, so the
    /// silence that follows does not read as one that went offline. A device
    /// on protocol 0x2C or later takes it only from its mesh controller or a
    /// management application, which this client announces itself as.
    pub fn reboot(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            Ok(Command::new(
                Addressee::device(d),
                op::SYS_REBOOT,
                build_target_only(d.uid),
            )
            .then(move |state, _| {
                if let Some(d) = state.device_mut(device) {
                    d.rebooting = true;
                }
            }))
        })
    }

    /// Asks a device to announce itself now.
    ///
    /// Its hello marks it online again, so a device suspected to be gone is
    /// confirmed or ruled out within a second or two rather than at the end of
    /// its silence window. A device that stays silent is not taken offline
    /// here: that remains the silence window's call.
    pub fn ping(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            Ok(Command::new(
                Addressee::device(d),
                op::SYS_PING,
                build_target_only(d.uid),
            ))
        })
    }

    /// Hands a OneIP source's stream addresses back to automatic assignment,
    /// undoing addresses that were set on it by hand.
    ///
    /// The device takes this only from management, which this client
    /// announces itself as. Nothing acknowledges it: the device's next
    /// configuration report carries the addresses it ends up with, and
    /// [`Remote::v2ip_details`] reads them.
    ///
    /// Refused for a device that is not a OneIP source, and for one below
    /// protocol 0x2B, which predates the operation and ignores it.
    pub fn auto_assign_v2ip_source_addresses(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            if !d.hello.features.has(DeviceFeature::V2IP_SOURCE) {
                return Err(ControlError::Unsupported(
                    "the device is not a OneIP source",
                ));
            }
            let have = d.hello.supported_protocol;
            if have != 0 && have < AUTO_ADDRESSES_PROTOCOL {
                return Err(ControlError::Send(SendError::ProtocolTooOld {
                    serial: d.serial().to_owned(),
                    opcode: op::MESH_OPERATION.0,
                    have,
                    need: AUTO_ADDRESSES_PROTOCOL,
                }));
            }
            Ok(Command::new(
                Addressee::device(d),
                op::MESH_OPERATION,
                build_mesh_operation(mesh_op::AUTO_ADDRESSES, d.uid),
            ))
        })
    }

    // ---- OneIP session descriptions ----

    /// Has a OneIP output play the stream a session description describes.
    ///
    /// The description goes out in pages of up to 1 KB, and the output plays
    /// it once the last page is in. It takes them only from its mesh
    /// controller or a management application, which this client announces
    /// itself as. Nothing acknowledges the pages: [`Remote::v2ip_sink_sdp`]
    /// reads what the output reports next. Refused for an empty description
    /// or one longer than [`V2IP_SDP_MAX`](crate::V2IP_SDP_MAX) bytes, for a
    /// device that is not a OneIP output, and for one below protocol 0x2E.
    pub fn play_v2ip_sdp(&self, device: DeviceUid, sdp: &str) -> Result<(), ControlError> {
        if sdp.is_empty() || sdp.len() > V2IP_SDP_MAX {
            return Err(ControlError::InvalidRequest(
                "a session description of 1 to 2048 bytes",
            ));
        }
        let (to, pages) = self.shared.read(|state| {
            let d = sdp_sink_of(state, device)?;
            Ok::<_, ControlError>((
                Addressee::device(d),
                build_sink_sdp_pages(d.uid, sdp.as_bytes()),
            ))
        })?;
        for page in pages {
            self.shared.send(&to, op::V2IP_SINK_SDP, &page)?;
        }
        Ok(())
    }

    /// Stops the stream a OneIP output plays from a session description. As
    /// [`Remote::play_v2ip_sdp`].
    pub fn stop_v2ip_sdp(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.sink_sdp_command(device, sdp_type::STOP, 0)
    }

    /// Sets what a OneIP output shows while it plays audio alone, as the wire
    /// value. As [`Remote::play_v2ip_sdp`].
    pub fn set_v2ip_sdp_screen(&self, device: DeviceUid, screen: u8) -> Result<(), ControlError> {
        self.sink_sdp_command(device, sdp_type::SCREEN, screen)
    }

    /// Asks a OneIP output what it plays from a session description now,
    /// rather than at its next report, which comes at least once a minute.
    /// As [`Remote::play_v2ip_sdp`].
    pub fn request_v2ip_sink_sdp(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.sink_sdp_command(device, sdp_type::REQUEST, 0)
    }

    /// Asks a OneIP output for what it plays from a session description and
    /// for the description itself, which
    /// [`Remote::v2ip_sink_description`] then reads. An output that plays
    /// none sends its status alone.
    ///
    /// Refused below protocol 0x31, where an output ignores the ask for the
    /// description. Otherwise as [`Remote::play_v2ip_sdp`].
    pub fn request_v2ip_sink_description(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = sdp_sink_of(state, device)?;
            let have = d.hello.supported_protocol;
            if have != 0 && have < SDP_DESCRIPTION_PROTOCOL {
                return Err(ControlError::Send(SendError::ProtocolTooOld {
                    serial: d.serial().to_owned(),
                    opcode: op::V2IP_SINK_SDP.0,
                    have,
                    need: SDP_DESCRIPTION_PROTOCOL,
                }));
            }
            Ok(Command::new(
                Addressee::device(d),
                op::V2IP_SINK_SDP,
                build_sink_sdp_command(d.uid, sdp_type::REQUEST, SDP_REQUEST_DESCRIPTION),
            ))
        })
    }

    /// Asks a OneIP source unit how its streams are encrypted now, rather than
    /// at its next report, which comes at least once a minute and whenever
    /// they change. [`Remote::v2ip_privacy`] reads the answer.
    ///
    /// Refused for a device that is not a OneIP source, and for one below
    /// protocol 0x30, which predates the report.
    pub fn request_v2ip_privacy(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            if !d.hello.features.has(DeviceFeature::V2IP_SOURCE) {
                return Err(ControlError::Unsupported(
                    "the device is not a OneIP source",
                ));
            }
            Ok(Command::new(
                Addressee::device(d),
                op::V2IP_PRIVACY,
                build_privacy_request(d.uid),
            ))
        })
    }

    /// Asks a unit for the message on its output, which
    /// [`Remote::osd_message`] reads once the unit answers.
    ///
    /// Refused for a device that is not a OneIP output.
    pub fn request_osd_message(&self, device: DeviceUid) -> Result<(), ControlError> {
        let none = OsdMessagePriority::LOW;
        self.send_osd_message(
            device,
            osd_kind::MESSAGE_REQUEST,
            OsdMessageFlag::NONE,
            0,
            none,
            "",
        )
    }

    /// Shows a message on a unit's output, in place of any it has.
    ///
    /// `logo` is shown with it: 0 the built-in logo, -1 none, 1 to 5 a logo
    /// slot. `text` is markup of at most
    /// [`OSD_MESSAGE_TEXT_MAX`](crate::OSD_MESSAGE_TEXT_MAX) bytes, with no
    /// control character; empty, the logo shows alone.
    ///
    /// The unit takes it from management, which this client announces itself
    /// as, and holds it until it restarts. It answers with the message it
    /// then has, which [`Remote::osd_message`] reads, flagged
    /// [`REFUSED`](OsdMessageFlag::REFUSED) when its video processor has no
    /// message layer. Refused here for a device that is not a OneIP output,
    /// and for a logo, priority or text the unit would refuse.
    pub fn show_osd_message(
        &self,
        device: DeviceUid,
        logo: i8,
        priority: OsdMessagePriority,
        text: &str,
    ) -> Result<(), ControlError> {
        if !(-1..=5).contains(&logo) {
            return Err(ControlError::InvalidRequest("a logo of -1 to 5"));
        }
        if priority > OsdMessagePriority::TOP {
            return Err(ControlError::InvalidRequest("no such message priority"));
        }
        if text.len() > OSD_MESSAGE_TEXT_MAX {
            return Err(ControlError::InvalidRequest(
                "a message of at most 255 bytes",
            ));
        }
        if text.bytes().any(|b| b < 0x20) {
            return Err(ControlError::InvalidRequest(
                "a control character in a message",
            ));
        }
        let set = OsdMessageFlag::SET;
        self.send_osd_message(device, osd_kind::MESSAGE_SET, set, logo, priority, text)
    }

    /// Takes the message down from a unit's output. As
    /// [`Remote::show_osd_message`].
    pub fn clear_osd_message(&self, device: DeviceUid) -> Result<(), ControlError> {
        let none = OsdMessagePriority::LOW;
        self.send_osd_message(
            device,
            osd_kind::MESSAGE_SET,
            OsdMessageFlag::NONE,
            0,
            none,
            "",
        )
    }

    /// The one send behind the message methods, to a OneIP output.
    fn send_osd_message(
        &self,
        device: DeviceUid,
        kind: u8,
        flags: OsdMessageFlag,
        logo: i8,
        priority: OsdMessagePriority,
        text: &str,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            if !d.is_v2ip_sink() {
                return Err(ControlError::Unsupported(
                    "the device is not a OneIP output",
                ));
            }
            Ok(Command::new(
                Addressee::device(d),
                op::V2IP_OSD_SYNC,
                build_osd_message(kind, d.uid, flags, logo, priority, text),
            ))
        })
    }

    /// Asks every OneIP source unit of the mesh how its streams are encrypted,
    /// as [`Remote::request_v2ip_privacy`] asks one. A unit below protocol
    /// 0x30 ignores it.
    pub fn request_all_v2ip_privacy(&self) -> Result<(), ControlError> {
        self.shared.send(
            &Addressee::Broadcast,
            op::V2IP_PRIVACY,
            &build_privacy_request(DeviceUid::ZERO),
        )?;
        Ok(())
    }

    /// The one send behind the session description commands.
    fn sink_sdp_command(&self, device: DeviceUid, kind: u8, value: u8) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = sdp_sink_of(state, device)?;
            Ok(Command::new(
                Addressee::device(d),
                op::V2IP_SINK_SDP,
                build_sink_sdp_command(d.uid, kind, value),
            ))
        })
    }

    // ---- units ----

    /// Clears a unit's current system status.
    ///
    /// The terms of [`Remote::upgrade_unit_fpga`] apply.
    pub fn clear_unit_status(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.unit_command(
            device,
            UnitCommandKind::CLEAR_STATUS,
            UnitCommandFlag::NONE,
            None,
        )
    }

    /// Upgrades a unit's video processor to the latest image it holds, or
    /// flashes that image again when `force` is set and it already runs it.
    ///
    /// The unit takes a command only from its mesh controller or a management
    /// application, which this client announces itself as. Nothing
    /// acknowledges it: [`Remote::unit_status`] reads what the unit reports
    /// next. Refused for a device that is not a OneIP unit, and for one below
    /// protocol 0x2C, which predates the command.
    pub fn upgrade_unit_fpga(&self, device: DeviceUid, force: bool) -> Result<(), ControlError> {
        let flags = if force {
            UnitCommandFlag::FORCE
        } else {
            UnitCommandFlag::NONE
        };
        self.unit_command(device, UnitCommandKind::FPGA_UPGRADE, flags, None)
    }

    /// Switches a unit to an IP configuration from DHCP.
    ///
    /// The terms of [`Remote::set_unit_network`] apply.
    pub fn set_unit_dhcp(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.unit_command(
            device,
            UnitCommandKind::NET_CONFIG,
            UnitCommandFlag::DHCP,
            Some(UnitNetConfig::default()),
        )
    }

    /// Gives a unit a static IP configuration.
    ///
    /// The address must be one a unit can hold and the netmask a run of ones
    /// from the top; anything else is refused before it is sent.
    ///
    /// The unit applies the change at once and reverts it unless its mesh
    /// controller, hearing the unit report it, confirms it in time.
    /// [`UnitStatus::network_pending`](crate::UnitStatus::network_pending) says
    /// whether it still waits, and
    /// [`Remote::confirm_unit_network`] confirms it. Otherwise as
    /// [`Remote::upgrade_unit_fpga`].
    pub fn set_unit_network(
        &self,
        device: DeviceUid,
        network: UnitNetConfig,
    ) -> Result<(), ControlError> {
        if !network.is_valid() {
            return Err(ControlError::InvalidRequest(
                "not an address and netmask a unit can hold",
            ));
        }
        self.unit_command(
            device,
            UnitCommandKind::NET_CONFIG,
            UnitCommandFlag::NONE,
            Some(network),
        )
    }

    /// Keeps a unit's pending IP configuration, as its mesh controller does
    /// when it hears the unit at its new address.
    ///
    /// The terms of [`Remote::upgrade_unit_fpga`] apply.
    pub fn confirm_unit_network(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.unit_command(
            device,
            UnitCommandKind::NET_CONFIRM,
            UnitCommandFlag::NONE,
            None,
        )
    }

    /// Locates a unit: its board-ID LED flashes, and an output shows "Locate
    /// Device" on its display. For 30 s when `timed` is set, until
    /// [`Remote::stop_locating_unit`] otherwise.
    ///
    /// Refused until the unit has reported its status, and for one whose
    /// report lacks [`UnitFlag::LOCATE_SUPPORTED`](crate::UnitFlag::LOCATE_SUPPORTED).
    /// The cached status takes [`UnitFlag::LOCATE`](crate::UnitFlag::LOCATE)
    /// at once, as the mesh controller's copy does; the unit reports its own
    /// within 2 s, and again when a timed locate ends. Otherwise as
    /// [`Remote::upgrade_unit_fpga`].
    pub fn locate_unit(&self, device: DeviceUid, timed: bool) -> Result<(), ControlError> {
        let flags = if timed {
            UnitCommandFlag::LOCATE_TIMED
        } else {
            UnitCommandFlag::LOCATE_ON
        };
        self.locate(device, flags)
    }

    /// Stops locating a unit. As [`Remote::locate_unit`].
    pub fn stop_locating_unit(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.locate(device, UnitCommandFlag::NONE)
    }

    /// The one send behind the locate methods.
    fn locate(&self, device: DeviceUid, flags: UnitCommandFlag) -> Result<(), ControlError> {
        let locating = !flags.is_empty();
        self.shared.command(move |state| {
            let command = unit_command_of(state, device, UnitCommandKind::LOCATE, flags, None)?;
            let status = device_of(state, device)?
                .unit_status
                .as_ref()
                .ok_or(ControlError::NotReported("the unit's status"))?;
            if !status.flags.has(UnitFlag::LOCATE_SUPPORTED) {
                return Err(ControlError::Unsupported("the unit cannot be located"));
            }
            Ok(command.then(move |state, ev| {
                let Some(d) = state.device_mut(device) else {
                    return;
                };
                let Some(mut status) = d.unit_status.clone() else {
                    return;
                };
                let bits = status.flags.bits() & !UnitFlag::LOCATE.bits();
                status.flags = UnitFlag::from_bits(bits);
                if locating {
                    status.flags |= UnitFlag::LOCATE;
                }
                d.set_unit_status(status, ev);
            }))
        })
    }

    /// The one send behind the unit command methods.
    fn unit_command(
        &self,
        device: DeviceUid,
        command: UnitCommandKind,
        flags: UnitCommandFlag,
        network: Option<UnitNetConfig>,
    ) -> Result<(), ControlError> {
        self.shared
            .command(move |state| unit_command_of(state, device, command, flags, network))
    }

    /// Sets the time zone of every device that hears it.
    ///
    /// `zone` is an IANA name such as `Europe/Amsterdam` and `rule` the POSIX
    /// TZ rule the devices keep time by, such as `CET-1CEST,M3.5.0,M10.5.0/3`.
    /// A device applies the rule and shows the name.
    /// Neither may be empty, hold a NUL, or be longer than its field on the
    /// wire leaves room for; [`Remote::clear_mesh_time_zone`] sends both empty.
    ///
    /// The mesh controller takes it too, and announces it from then on with
    /// every periodic broadcast. A device takes it only from a management
    /// application or the controller, and this client announces itself as a
    /// management application.
    pub fn set_mesh_time_zone(&self, zone: &str, rule: &str) -> Result<(), ControlError> {
        let fits = |s: &str, len: usize| !s.is_empty() && s.len() < len && !s.contains('\0');
        if !fits(zone, TIME_ZONE_NAME_LEN) || !fits(rule, TIME_ZONE_RULE_LEN) {
            return Err(ControlError::InvalidRequest(
                "a time zone name or rule is empty, holds a NUL, or is too long",
            ));
        }
        self.shared.send(
            &Addressee::Broadcast,
            op::TIME_ZONE,
            &build_time_zone(zone, rule),
        )?;
        Ok(())
    }

    /// Clears the time zone of every device that hears it, which then keeps
    /// UTC. Sent, received and announced as [`Remote::set_mesh_time_zone`]
    /// with an empty name and rule.
    pub fn clear_mesh_time_zone(&self) -> Result<(), ControlError> {
        self.shared.send(
            &Addressee::Broadcast,
            op::TIME_ZONE,
            &build_time_zone("", ""),
        )?;
        Ok(())
    }

    /// Sets the clock of every device that hears it to `time`.
    ///
    /// A device keeps its own clock where that is within 2s of `time`. It takes
    /// the time only from a management application or the controller; see
    /// [`Remote::set_mesh_time_zone`]. A time before 1970 or past what 32 bits
    /// of seconds hold, in 2106, is refused.
    pub fn set_mesh_time(&self, time: SystemTime) -> Result<(), ControlError> {
        let utc = time
            .duration_since(UNIX_EPOCH)
            .ok()
            .and_then(|d| u32::try_from(d.as_secs()).ok())
            .ok_or(ControlError::InvalidRequest(
                "the time does not fit the frame",
            ))?;
        self.shared
            .send(&Addressee::Broadcast, op::TIME, &utc.to_le_bytes())?;
        Ok(())
    }

    /// Tells every unit to check its update server for new firmware now.
    pub fn send_monitoring_pulse(&self) -> Result<(), ControlError> {
        self.shared
            .send(&Addressee::Broadcast, op::SYS_MONITORING_PULSE, &[])?;
        Ok(())
    }

    /// Sends an application's own message to every device, under `vendor`.
    ///
    /// Every other client of this library that has heard this one announce
    /// itself receives it at [`crate::EventHandler::on_third_party_message`];
    /// this client does not, and neither does one sharing its identifier. No
    /// unit is meant to read it. Nothing acknowledges it, so an application
    /// that needs to know it arrived has to have its peers answer.
    ///
    /// A payload over [`crate::THIRD_PARTY_PAYLOAD_MAX`] bytes is refused.
    pub fn send_third_party(
        &self,
        vendor: ThirdPartyVendor,
        payload: &[u8],
    ) -> Result<(), ControlError> {
        if payload.len() > THIRD_PARTY_PAYLOAD_MAX {
            return Err(ControlError::InvalidRequest(
                "a third-party payload is at most 1444 bytes",
            ));
        }
        self.shared.send(
            &Addressee::Broadcast,
            op::THIRD_PARTY,
            &build_third_party(vendor, payload),
        )?;
        Ok(())
    }

    // ---- OneIP scaling ----

    /// Turns a OneIP sink's automatic scaling on or off.
    ///
    /// Refused for a unit below protocol 0x2F: released firmware drops a
    /// scaling write from management.
    ///
    /// Automatic scaling and a configured output mode are separate reasons for
    /// a sink to scale, and this moves only the first: a sink with a mode
    /// configured goes on scaling to it with automatic scaling off. Turning
    /// both off is this call plus [`Remote::clear_v2ip_output_mode`].
    ///
    /// Nothing acknowledges the frame. Read the sink back through
    /// [`Remote::v2ip_details`] to learn what it did, and treat the block as
    /// meaningful only where [`crate::DeviceInfo::config_initialised`] is set.
    /// **Read any route you still need before writing.** The sink rebuilds
    /// and rebroadcasts its subscription in response, and that report can
    /// arrive empty for up to a minute; [`crate::DeviceV2ipSink`] says when
    /// and why.
    pub fn set_v2ip_auto_scaling(
        &self,
        device: DeviceUid,
        enabled: bool,
    ) -> Result<(), ControlError> {
        let written = if enabled {
            SCALING_FLAG_OPTIONS_VALID | SCALING_FLAG_AUTO_SCALING
        } else {
            SCALING_FLAG_OPTIONS_VALID
        };
        self.set_v2ip_scaling(device, MxrSignalType::NONE, 0, written, move |cached| {
            V2ipScalingSettings {
                flags: (cached.flags & !SCALING_FLAG_AUTO_SCALING)
                    | SCALING_FLAG_OPTIONS_VALID
                    | (written & SCALING_FLAG_AUTO_SCALING),
                ..cached
            }
        })
    }

    /// Sets the output format a OneIP sink scales to.
    ///
    /// Refused for a unit below protocol 0x2F: released firmware drops a
    /// scaling write from management.
    ///
    /// The mode is checked here and nothing is sent if it fails, because every
    /// value a sink refuses it refuses in silence. Passing that check is not a
    /// guarantee: the sink also weighs the format against the display's EDID
    /// and against what its own output stage can produce.
    ///
    /// **Turn automatic scaling off first if it is on.** A sink refuses a mode
    /// whose format the attached display does not list while it is scaling
    /// automatically, and refuses it silently. Setting a mode and then turning
    /// automatic scaling back on is the order that survives, because the mode
    /// is checked while automatic scaling is still off.
    ///
    /// Configuring a mode is itself a reason to scale, so a sink with one
    /// scales whether or not automatic scaling is on.
    ///
    /// **Pass a descriptor and a refresh rate that agree.** A sink stores both
    /// halves and, with its match-source setting on as it ships, reports back
    /// the descriptor matching the refresh it holds: a 60Hz descriptor written
    /// with a refresh of 50 reads back as that descriptor's 50Hz sibling, once,
    /// and stays there. A sink with match-source off reports the descriptor it
    /// was given. Either way a pair that agrees reads back unchanged, and the
    /// format driven is the same - so this costs a caller nothing except a
    /// descriptor it did not write. That substitution shows up on the sink's
    /// next report rather than immediately, because
    /// [`crate::V2ipScalingSettings`] holds what was written until then.
    ///
    /// A mode read from the sink's own web interface is not interchangeable
    /// with this pair. That interface reports the descriptor's 60Hz sibling and
    /// carries the refresh in a field of its own, so writing back what it shows
    /// as the mode, on its own, changes the setting rather than restoring it.
    /// **Read any route you still need before writing.** The sink rebuilds
    /// and rebroadcasts its subscription in response, and that report can
    /// arrive empty for up to a minute; [`crate::DeviceV2ipSink`] says when
    /// and why.
    pub fn set_v2ip_output_mode(
        &self,
        device: DeviceUid,
        mode: V2ipOutputMode,
    ) -> Result<(), ControlError> {
        mode.validate().map_err(ControlError::InvalidRequest)?;
        let signal = mode.to_signal_type();
        let refresh = mode.refresh;
        self.set_v2ip_scaling(
            device,
            signal,
            refresh,
            SCALING_FLAG_MODE_VALID,
            move |cached| V2ipScalingSettings {
                mode: signal,
                refresh,
                flags: cached.flags | SCALING_FLAG_MODE_VALID,
            },
        )
    }

    /// Clears the output format a OneIP sink is configured to scale to.
    ///
    /// Refused for a unit below protocol 0x2F: released firmware drops a
    /// scaling write from management.
    ///
    /// The sink stops scaling for that reason and keeps its automatic scaling
    /// setting, so a sink scaling for both reasons goes on scaling until
    /// [`Remote::set_v2ip_auto_scaling`] turns the other one off.
    ///
    /// This is the only way to express "no mode configured", and it is what a
    /// caller restoring a sink that had none has to send: a sink reports no
    /// mode by leaving the mode's valid bit clear, which is not something a
    /// write can say.
    /// **Read any route you still need before writing.** The sink rebuilds
    /// and rebroadcasts its subscription in response, and that report can
    /// arrive empty for up to a minute; [`crate::DeviceV2ipSink`] says when
    /// and why.
    pub fn clear_v2ip_output_mode(&self, device: DeviceUid) -> Result<(), ControlError> {
        // The valid bit with a zero descriptor is the clear. The receiver takes
        // that branch ahead of validating anything, and ignores the depth,
        // colour space and refresh rate beside it.
        self.set_v2ip_scaling(
            device,
            MxrSignalType::NONE,
            0,
            SCALING_FLAG_MODE_VALID,
            |cached| V2ipScalingSettings {
                mode: MxrSignalType::NONE,
                refresh: 0,
                flags: cached.flags & !SCALING_FLAG_MODE_VALID,
            },
        )
    }

    /// The one send behind the scaling methods.
    ///
    /// `written` is the flag byte that goes out, and `applied` says what the
    /// sink will report afterwards. The two differ where the wire spells a
    /// write differently from the state it produces - clearing a mode is sent
    /// as the valid bit over a zero mode and read back as the valid bit clear -
    /// so predicting the cached value from the frame alone would leave a
    /// caller reading a state no device ever broadcasts.
    fn set_v2ip_scaling(
        &self,
        device: DeviceUid,
        mode: MxrSignalType,
        refresh: u16,
        written: u8,
        applied: impl FnOnce(V2ipScalingSettings) -> V2ipScalingSettings + Send + 'static,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            if !d.is_v2ip_sink() {
                return Err(ControlError::Unsupported(
                    "scaling settings need a OneIP sink",
                ));
            }
            // A unit below this protocol drops a scaling write from
            // management.
            if d.hello.supported_protocol < SCALING_WRITE_PROTOCOL {
                return Err(ControlError::Unsupported(
                    "the unit's firmware ignores scaling writes",
                ));
            }
            Ok(Command::new(
                Addressee::device(d),
                op::V2IP_DEVICE_CFG,
                build_v2ip_scaling(d.uid, mode, refresh, written),
            )
            .then(move |state, ev| {
                if let Some(d) = state.device_mut(device) {
                    let cached = d.v2ip_scaling();
                    d.set_v2ip_scaling(applied(cached), ev);
                }
            }))
        })
    }

    // ---- OneIP device settings ----

    /// Switches on/off settings of a OneIP device, all to the same value.
    ///
    /// `setting` names one or more of [`V2ipDeviceSetting::SWITCHES`], and
    /// each must be one the device has reported: a device ignores a setting it
    /// does not have, so a write for one would read back as applied here and
    /// change nothing there.
    ///
    /// Nothing acknowledges the frame. The device answers by reporting its
    /// settings, and until then [`Remote::v2ip_device_settings`] reads back
    /// what was written.
    pub fn set_v2ip_device_setting(
        &self,
        device: DeviceUid,
        setting: V2ipDeviceSetting,
        enabled: bool,
    ) -> Result<(), ControlError> {
        if setting.is_empty() || !setting.without(V2ipDeviceSetting::SWITCHES).is_empty() {
            return Err(ControlError::InvalidRequest(
                "only on/off device settings are switched",
            ));
        }
        self.set_v2ip_device_settings(
            device,
            V2ipDeviceSettings {
                valid: setting,
                flags: if enabled {
                    setting
                } else {
                    V2ipDeviceSetting::NONE
                },
                ..V2ipDeviceSettings::default()
            },
        )
    }

    /// Sets the infrared profile of a OneIP device's global infrared port.
    ///
    /// `profile` is below [`V2IP_IR_PROFILE_MAX`], and is checked here because
    /// a device ignores one out of range. The terms of
    /// [`Remote::set_v2ip_device_setting`] apply.
    pub fn set_v2ip_ir_profile(&self, device: DeviceUid, profile: i8) -> Result<(), ControlError> {
        if !(0..V2IP_IR_PROFILE_MAX).contains(&profile) {
            return Err(ControlError::InvalidRequest("no such infrared profile"));
        }
        self.set_v2ip_device_settings(
            device,
            V2ipDeviceSettings {
                valid: V2ipDeviceSetting::IR_PROFILE,
                ir_profile: profile,
                ..V2ipDeviceSettings::default()
            },
        )
    }

    /// Sets the infrared profile of a OneIP device's output infrared port.
    ///
    /// [`V2IP_IR_PROFILE_NOT_SET`] makes the port follow the global one.
    /// Otherwise as [`Remote::set_v2ip_ir_profile`].
    pub fn set_v2ip_sink_ir_profile(
        &self,
        device: DeviceUid,
        profile: i8,
    ) -> Result<(), ControlError> {
        if !(V2IP_IR_PROFILE_NOT_SET..V2IP_IR_PROFILE_MAX).contains(&profile) {
            return Err(ControlError::InvalidRequest("no such infrared profile"));
        }
        self.set_v2ip_device_settings(
            device,
            V2ipDeviceSettings {
                valid: V2ipDeviceSetting::IR_PROFILE_SINK,
                ir_profile_sink: profile,
                ..V2ipDeviceSettings::default()
            },
        )
    }

    /// Sets how many idle minutes a OneIP device waits before it powers down by
    /// itself, 0 for never. The terms of [`Remote::set_v2ip_device_setting`]
    /// apply.
    pub fn set_v2ip_auto_power_save(
        &self,
        device: DeviceUid,
        minutes: u16,
    ) -> Result<(), ControlError> {
        self.set_v2ip_device_settings(
            device,
            V2ipDeviceSettings {
                valid: V2ipDeviceSetting::AUTO_POWER_SAVE,
                auto_power_save: minutes,
                ..V2ipDeviceSettings::default()
            },
        )
    }

    /// Sets a OneIP device's daily power save windows.
    ///
    /// Every time is below [`V2IP_MINUTES_PER_DAY`](crate::V2IP_MINUTES_PER_DAY),
    /// and is checked here.
    /// The windows are kept in the device's own time zone. The terms of
    /// [`Remote::set_v2ip_device_setting`] apply.
    pub fn set_v2ip_power_save_schedule(
        &self,
        device: DeviceUid,
        schedule: V2ipPowerSaveSchedule,
    ) -> Result<(), ControlError> {
        if !schedule.is_valid() {
            return Err(ControlError::InvalidRequest(
                "a power save time is not a time of day",
            ));
        }
        self.set_v2ip_device_settings(
            device,
            V2ipDeviceSettings {
                valid: V2ipDeviceSetting::POWER_SAVE_SCHEDULE,
                power_save: schedule,
                ..V2ipDeviceSettings::default()
            },
        )
    }

    /// Switches a OneIP device's power save on, so it powers down by itself
    /// to the level it picks, or off, so it powers down only when asked.
    ///
    /// On is written as a mesh controller writes it: both
    /// [`POWER_SAVE_DISABLED`](V2ipDeviceSetting::POWER_SAVE_DISABLED), clear,
    /// and [`POWER_SAVE_LEVEL`](V2ipDeviceSetting::POWER_SAVE_LEVEL), at 0, so
    /// a device whose firmware takes the level as its setting returns to its
    /// own default. The terms of [`Remote::set_v2ip_device_setting`] apply.
    pub fn set_v2ip_power_save(
        &self,
        device: DeviceUid,
        enabled: bool,
    ) -> Result<(), ControlError> {
        self.set_v2ip_device_settings(device, power_save_switch(enabled))
    }

    /// Switches power save on or off on every OneIP device of the mesh with
    /// one frame, written as [`Remote::set_v2ip_power_save`] writes it. As
    /// [`Remote::set_all_v2ip_device_settings`], which carries the other
    /// settings.
    pub fn set_all_v2ip_power_save(&self, enabled: bool) -> Result<(), ControlError> {
        self.set_all_v2ip_device_settings(power_save_switch(enabled))
    }

    /// Writes the level a OneIP device powers down to in power save, which
    /// switches power save on.
    ///
    /// A device picks its level itself and ignores the one written, except
    /// one whose firmware predates picking it, which takes the level as its
    /// setting. A level that unit does not offer is one its
    /// [`UnitStatus`](crate::UnitStatus) reports without
    /// [`SUPPORTED`](crate::UnitPowerSave::SUPPORTED). The level is not
    /// cached: [`V2ipDeviceSettings::power_save_level`] reads what the device
    /// reports. [`Remote::set_v2ip_power_save`] switches power save on or off
    /// without naming a level. The terms of
    /// [`Remote::set_v2ip_device_setting`] apply.
    pub fn set_v2ip_power_save_level(
        &self,
        device: DeviceUid,
        level: V2ipPowerSaveLevel,
    ) -> Result<(), ControlError> {
        if level > V2ipPowerSaveLevel::OFF {
            return Err(ControlError::InvalidRequest("no such power save level"));
        }
        self.set_v2ip_device_settings(
            device,
            V2ipDeviceSettings {
                valid: V2ipDeviceSetting::POWER_SAVE_LEVEL,
                power_save_level: level,
                ..V2ipDeviceSettings::default()
            },
        )
    }

    /// Sets how a OneIP device paces its PTP messages, its SAP timings, its
    /// streams' TTL and its output's rotation: the values of `messages` behind
    /// the bits of `which`, each one of
    /// [`SETTINGS_BLOCK`](V2ipDeviceSetting::SETTINGS_BLOCK). A DSCP above
    /// [`V2IP_DSCP_MAX`](crate::V2IP_DSCP_MAX), a stream TTL of 0 and a
    /// rotation that is not 0 or a multiple of the step the device reports
    /// are refused. The terms of [`Remote::set_v2ip_device_setting`] apply.
    pub fn set_v2ip_ptp_messages(
        &self,
        device: DeviceUid,
        which: V2ipDeviceSetting,
        messages: V2ipPtpMessages,
    ) -> Result<(), ControlError> {
        if which.is_empty() || !V2ipDeviceSetting::SETTINGS_BLOCK.has(which) {
            return Err(ControlError::InvalidRequest(
                "only PTP message, SAP timing, stream TTL and rotation settings are carried here",
            ));
        }
        if which.has(V2ipDeviceSetting::PTP_DSCP) && messages.dscp > V2IP_DSCP_MAX {
            return Err(ControlError::InvalidRequest("a DSCP above 63"));
        }
        if which.has(V2ipDeviceSetting::STREAM_TTL) && messages.stream_ttl == 0 {
            return Err(ControlError::InvalidRequest("a stream TTL of 0"));
        }
        self.set_v2ip_device_settings(
            device,
            V2ipDeviceSettings {
                valid: which,
                ptp_messages: messages,
                ..V2ipDeviceSettings::default()
            },
        )
    }

    /// Sets how a OneIP device's output mixes 5.1 and 7.1 PCM down to stereo:
    /// the mode, level and LFE percent of `downmix`, which the device applies
    /// together. Its state and channels are the device's to report, and are
    /// not sent.
    ///
    /// Refused before anything is sent for a mode, level or LFE percent out of
    /// range, and unless the device reports a downmix, which one whose output
    /// cannot mix down never does. The new downmix is cached once the frame
    /// is sent, and the device's next report replaces it.
    pub fn set_v2ip_downmix(
        &self,
        device: DeviceUid,
        downmix: V2ipDownmix,
    ) -> Result<(), ControlError> {
        if !downmix.is_valid() {
            return Err(ControlError::InvalidRequest(
                "no such downmix mode or level, or an LFE above 100 percent",
            ));
        }
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            if d.v2ip_settings.is_none() {
                return Err(ControlError::NotReported("the device's settings"));
            }
            let Some(reported) = d.v2ip_downmix else {
                return Err(ControlError::Unsupported(
                    "the device does not mix its output down",
                ));
            };
            Ok(Command::new(
                Addressee::device(d),
                op::V2IP_DEVICE_CFG,
                build_v2ip_downmix(d.uid, &downmix),
            )
            .then(move |state, ev| {
                if let Some(d) = state.device_mut(device) {
                    d.set_v2ip_downmix(Some(reported.written(downmix)), ev);
                }
            }))
        })
    }

    /// Sets the PTP mode a OneIP device runs. The terms of
    /// [`Remote::set_v2ip_device_setting`] apply.
    pub fn set_v2ip_ptp_mode(
        &self,
        device: DeviceUid,
        mode: V2ipPtpMode,
    ) -> Result<(), ControlError> {
        if mode > V2ipPtpMode::AUTO {
            return Err(ControlError::InvalidRequest("no such PTP mode"));
        }
        self.set_v2ip_device_settings(
            device,
            V2ipDeviceSettings {
                valid: V2ipDeviceSetting::PTP_MODE,
                ptp_mode: mode,
                ..V2ipDeviceSettings::default()
            },
        )
    }

    /// Sets the PTP domain a OneIP device runs in, at most
    /// [`V2IP_PTP_DOMAIN_MAX`](crate::V2IP_PTP_DOMAIN_MAX). The terms of
    /// [`Remote::set_v2ip_device_setting`] apply.
    pub fn set_v2ip_ptp_domain(&self, device: DeviceUid, domain: u8) -> Result<(), ControlError> {
        if domain > V2IP_PTP_DOMAIN_MAX {
            return Err(ControlError::InvalidRequest("no such PTP domain"));
        }
        self.set_v2ip_device_settings(
            device,
            V2ipDeviceSettings {
                valid: V2ipDeviceSetting::PTP_DOMAIN,
                ptp_domain: domain,
                ..V2ipDeviceSettings::default()
            },
        )
    }

    /// Sets the priority1 a OneIP device announces as a PTP grandmaster, lower
    /// winning. The terms of [`Remote::set_v2ip_device_setting`] apply.
    pub fn set_v2ip_ptp_priority1(
        &self,
        device: DeviceUid,
        priority1: u8,
    ) -> Result<(), ControlError> {
        self.set_v2ip_device_settings(
            device,
            V2ipDeviceSettings {
                valid: V2ipDeviceSetting::PTP_PRIORITY1,
                ptp_priority1: priority1,
                ..V2ipDeviceSettings::default()
            },
        )
    }

    /// Changes settings on every OneIP device of the mesh with one frame.
    ///
    /// `settings` carries the settings behind their bits in
    /// [`valid`](V2ipDeviceSettings::valid), as a device reports them. Each
    /// device applies those it has and ignores the rest, and none that
    /// predates the frame applies any. A setting only a device reports about
    /// itself, a profile, PTP mode, PTP domain, power save level or PTP DSCP
    /// out of range, a stream TTL of 0, a rotation above
    /// [`V2IP_SINK_ROTATION_MAX`](crate::V2IP_SINK_ROTATION_MAX) and a
    /// schedule time that is not a time of day are refused here, since every
    /// device would ignore them. Each device takes a rotation only by its own
    /// step.
    ///
    /// Nothing is cached: each device that applies a change reports its
    /// settings, and [`Remote::v2ip_device_settings`] reads that.
    pub fn set_all_v2ip_device_settings(
        &self,
        settings: V2ipDeviceSettings,
    ) -> Result<(), ControlError> {
        let valid = settings.valid;
        if valid.is_empty() {
            return Err(ControlError::InvalidRequest("no setting is carried"));
        }
        if !(valid & V2ipDeviceSetting::REPORTED_ONLY).is_empty() {
            return Err(ControlError::InvalidRequest(
                "a setting only a device reports is carried",
            ));
        }
        if valid.has(V2ipDeviceSetting::IR_PROFILE)
            && !(0..V2IP_IR_PROFILE_MAX).contains(&settings.ir_profile)
        {
            return Err(ControlError::InvalidRequest("no such infrared profile"));
        }
        if valid.has(V2ipDeviceSetting::IR_PROFILE_SINK)
            && !(V2IP_IR_PROFILE_NOT_SET..V2IP_IR_PROFILE_MAX).contains(&settings.ir_profile_sink)
        {
            return Err(ControlError::InvalidRequest("no such infrared profile"));
        }
        if valid.has(V2ipDeviceSetting::POWER_SAVE_SCHEDULE) && !settings.power_save.is_valid() {
            return Err(ControlError::InvalidRequest(
                "a power save time is not a time of day",
            ));
        }
        if valid.has(V2ipDeviceSetting::PTP_MODE) && settings.ptp_mode > V2ipPtpMode::AUTO {
            return Err(ControlError::InvalidRequest("no such PTP mode"));
        }
        if valid.has(V2ipDeviceSetting::PTP_DOMAIN) && settings.ptp_domain > V2IP_PTP_DOMAIN_MAX {
            return Err(ControlError::InvalidRequest("no such PTP domain"));
        }
        if valid.has(V2ipDeviceSetting::POWER_SAVE_LEVEL)
            && settings.power_save_level > V2ipPowerSaveLevel::OFF
        {
            return Err(ControlError::InvalidRequest("no such power save level"));
        }
        if valid.has(V2ipDeviceSetting::PTP_DSCP) && settings.ptp_messages.dscp > V2IP_DSCP_MAX {
            return Err(ControlError::InvalidRequest("a DSCP above 63"));
        }
        if valid.has(V2ipDeviceSetting::STREAM_TTL) && settings.ptp_messages.stream_ttl == 0 {
            return Err(ControlError::InvalidRequest("a stream TTL of 0"));
        }
        if valid.has(V2ipDeviceSetting::SINK_ROTATION)
            && settings.ptp_messages.sink_rotation > V2IP_SINK_ROTATION_MAX
        {
            return Err(ControlError::InvalidRequest("a rotation above 359 degrees"));
        }
        self.shared.send(
            &Addressee::Broadcast,
            op::V2IP_SETTINGS_ALL,
            &build_v2ip_settings_all(&settings),
        )?;
        Ok(())
    }

    /// The one send behind the device settings methods.
    fn set_v2ip_device_settings(
        &self,
        device: DeviceUid,
        settings: V2ipDeviceSettings,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            let Some(reported) = d.v2ip_settings else {
                return Err(ControlError::NotReported("the device's settings"));
            };
            if !reported.valid.has(settings.valid) {
                return Err(ControlError::Unsupported(
                    "the device does not have this setting",
                ));
            }
            if settings.valid.has(V2ipDeviceSetting::SINK_ROTATION)
                && !reported
                    .ptp_messages
                    .takes_sink_rotation(settings.ptp_messages.sink_rotation)
            {
                return Err(ControlError::InvalidRequest(
                    "the device does not turn its output by this angle",
                ));
            }
            let cached = settings.as_applied_to(&reported);
            Ok(Command::new(
                Addressee::device(d),
                op::V2IP_DEVICE_CFG,
                build_v2ip_device_settings(d.uid, &settings),
            )
            .then(move |state, ev| {
                if let Some(d) = state.device_mut(device) {
                    d.merge_v2ip_settings(cached, ev);
                }
            }))
        })
    }

    // ---- OneIP VLAN ----

    /// Changes a OneIP device's VLAN configuration.
    ///
    /// Writes the VLAN ids, the pinned uplink and the
    /// [`TRUNK`](V2ipVlanFlag::TRUNK) flag of `vlan`; its other flags and the
    /// fields only the device reports are not sent. Refused before anything is
    /// sent unless the device announces [`DeviceFeature::VLAN`] and has
    /// reported its configuration, every id is at most
    /// [`V2IP_VLAN_ID_MAX`](crate::V2IP_VLAN_ID_MAX), and the uplink is
    /// detected or names a port the device has.
    ///
    /// The device applies the change at once and reverts it unless the mesh
    /// controller, hearing the device report it, confirms it. Nothing is
    /// cached here: [`Remote::v2ip_vlan`] reads what the device reports, and
    /// [`V2ipVlan::is_pending`] whether it is still to be confirmed.
    pub fn set_v2ip_vlan(&self, device: DeviceUid, vlan: V2ipVlan) -> Result<(), ControlError> {
        if !vlan.is_valid() {
            return Err(ControlError::InvalidRequest(
                "a VLAN id is out of range or the uplink names no port",
            ));
        }
        let written = V2ipVlan {
            flags: V2ipVlanFlag::VALID | (vlan.flags & V2ipVlanFlag::TRUNK),
            device: vlan.device,
            port: vlan.port,
            uplink: vlan.uplink,
            active_uplink: 0,
            revert_s: 0,
        };
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            if !d.hello.features.has(DeviceFeature::VLAN) {
                return Err(ControlError::Unsupported("the device does not take VLANs"));
            }
            let Some(reported) = d.v2ip_vlan else {
                return Err(ControlError::NotReported("the device's VLAN configuration"));
            };
            if written.pinned_uplink() == Some(V2IP_VLAN_PORT_SFP) && !reported.has_sfp() {
                return Err(ControlError::Unsupported("the device has no SFP port"));
            }
            Ok(Command::new(
                Addressee::device(d),
                op::V2IP_DEVICE_CFG,
                build_v2ip_vlan(d.uid, &written),
            ))
        })
    }

    // ---- OneIP test card ----

    /// Asks a OneIP sink for its test card, which it reports straight back;
    /// [`Remote::v2ip_testcard`] reads it.
    ///
    /// Refused unless the sink's video processor has reported
    /// [`SINK_TEST_PATTERN`](V2ipFpgaFeature::SINK_TEST_PATTERN). A sink with
    /// that feature but without the module that draws the test card does not
    /// answer.
    pub fn request_v2ip_testcard(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.send_v2ip_testcard(device, testcard_type::REQUEST, 0, V2ipTestcard::default())
    }

    /// Shows a test pattern on a OneIP sink's output, or none for
    /// [`V2ipTestPattern::OFF`]. `colour` is `0xRRGGBB`, used by
    /// [`V2ipTestPattern::FLAT`].
    ///
    /// A pattern runs until it is turned off, and holds the output on while it
    /// does. The sink reports its test card in answer. Refused as
    /// [`Remote::request_v2ip_testcard`] is, and for a pattern this library
    /// does not name or a colour above `0xFFFFFF`.
    pub fn set_v2ip_test_pattern(
        &self,
        device: DeviceUid,
        pattern: V2ipTestPattern,
        colour: u32,
    ) -> Result<(), ControlError> {
        if pattern.to_wire() > V2ipTestPattern::CARD.to_wire() || colour > 0x00FF_FFFF {
            return Err(ControlError::InvalidRequest(
                "no such test pattern, or a colour wider than 24 bits",
            ));
        }
        self.send_v2ip_testcard(
            device,
            testcard_type::SET,
            testcard_part::PATTERN,
            V2ipTestcard {
                pattern,
                colour,
                ..V2ipTestcard::default()
            },
        )
    }

    /// Plays a test tone on a OneIP sink's output.
    ///
    /// Every value is checked here, as the sink ignores a tone that is not
    /// [`V2ipTestTone::is_valid`]; [`V2ipToneMode::OFF`] stops it whatever the
    /// rest holds, and the sink keeps those values as its last ones. Otherwise
    /// as [`Remote::set_v2ip_test_pattern`].
    pub fn set_v2ip_test_tone(
        &self,
        device: DeviceUid,
        tone: V2ipTestTone,
    ) -> Result<(), ControlError> {
        if tone.mode != V2ipToneMode::OFF && !tone.is_valid() {
            return Err(ControlError::InvalidRequest(
                "a test tone value is out of range",
            ));
        }
        self.send_v2ip_testcard(
            device,
            testcard_type::SET,
            testcard_part::TONE,
            V2ipTestcard {
                tone,
                ..V2ipTestcard::default()
            },
        )
    }

    /// Sets a OneIP sink's lip-sync flash.
    ///
    /// Checked here as [`V2ipTestSync::is_valid`], since the sink ignores
    /// settings that are not. Otherwise as [`Remote::set_v2ip_test_pattern`].
    pub fn set_v2ip_test_sync(
        &self,
        device: DeviceUid,
        sync: V2ipTestSync,
    ) -> Result<(), ControlError> {
        if !sync.is_valid() {
            return Err(ControlError::InvalidRequest(
                "a lip-sync value is out of range",
            ));
        }
        self.send_v2ip_testcard(
            device,
            testcard_type::SET,
            testcard_part::SYNC,
            V2ipTestcard {
                sync,
                ..V2ipTestcard::default()
            },
        )
    }

    /// The one send behind the test card methods. Nothing is cached: the sink
    /// answers every frame with its test card.
    fn send_v2ip_testcard(
        &self,
        device: DeviceUid,
        kind: u8,
        parts: u8,
        testcard: V2ipTestcard,
    ) -> Result<(), ControlError> {
        self.shared.command(move |state| {
            let d = device_of(state, device)?;
            let Some(features) = d.v2ip_features else {
                return Err(ControlError::NotReported(
                    "the sink's video processor features",
                ));
            };
            if !features.has(V2ipFpgaFeature::SINK_TEST_PATTERN) {
                return Err(ControlError::Unsupported(
                    "the sink cannot draw a test card",
                ));
            }
            Ok(Command::new(
                Addressee::device(d),
                op::V2IP_TESTCARD,
                build_v2ip_testcard(d.uid, kind, parts, &testcard),
            ))
        })
    }

    // ---- video wall ----

    /// Shows a window on a sink's video wall without persisting it.
    ///
    /// The window survives until the sink is told otherwise or restarts.
    /// [`Remote::revert_video_wall`] puts back whatever was stored.
    ///
    /// Pass [`crate::VIDEO_WALL_CLEARED`] to show the whole frame again.
    pub fn preview_video_wall(
        &self,
        sink: DeviceUid,
        window: VideoWallWindow,
    ) -> Result<(), ControlError> {
        self.set_video_wall(sink, window, VideoWallOp::PREVIEW)
    }

    /// Persists a window as a sink's video wall.
    ///
    /// The geometry is checked here, before anything is sent, because the sink
    /// is not guaranteed to check it. A sink running a video-wall module older
    /// than 2026083100 writes the window to its configuration *before* asking
    /// its video processor to apply it, and the processor's refusal does not
    /// undo that write - so an out-of-spec window survives a reboot and is
    /// re-offered on every stream restart until something else replaces it. A
    /// power cycle does not clear it.
    ///
    /// Nothing acknowledges this frame either way, so an `Ok` says only that
    /// it was sent. Read the sink's state back to learn what it did.
    ///
    /// Pass [`crate::VIDEO_WALL_CLEARED`] to store "show the whole frame".
    pub fn store_video_wall(
        &self,
        sink: DeviceUid,
        window: VideoWallWindow,
    ) -> Result<(), ControlError> {
        self.set_video_wall(sink, window, VideoWallOp::STORE)
    }

    /// Restores the window a sink has stored, discarding a preview.
    ///
    /// Carries no window of its own: the sink already holds the one this puts
    /// back.
    pub fn revert_video_wall(&self, sink: DeviceUid) -> Result<(), ControlError> {
        self.set_video_wall(sink, VIDEO_WALL_CLEARED, VideoWallOp::REVERT)
    }

    /// The one send behind the three video-wall methods.
    ///
    /// Validation sits here rather than in each of them, so an operation added
    /// later cannot reach the wire without it, and is skipped for a revert
    /// because the sink ignores the window on that operation rather than
    /// checking it.
    ///
    /// Refused for a unit that does not report
    /// [`VIDEO_WALL`](DeviceFeature::VIDEO_WALL), which drops the frame
    /// unanswered.
    ///
    /// Passing it is not proof a wall appeared. Two things the sink refuses
    /// afterwards are equally silent: a window it will not draw, which it logs
    /// and drops, and a sink whose image has no tiling support at all, which
    /// takes the window into its own state and then fails to push it to the
    /// hardware. Neither reaches the wire, so read the sink back over HTTP to
    /// learn a window landed.
    fn set_video_wall(
        &self,
        sink: DeviceUid,
        window: VideoWallWindow,
        op: VideoWallOp,
    ) -> Result<(), ControlError> {
        if op != VideoWallOp::REVERT {
            window.validate().map_err(ControlError::InvalidRequest)?;
        }
        self.shared.command(move |state| {
            let device = device_of(state, sink)?;
            // A unit without the module drops the frame unanswered.
            if !device.hello.features.has(DeviceFeature::VIDEO_WALL) {
                return Err(ControlError::Unsupported("the unit has no video wall"));
            }
            Ok(Command::new(
                Addressee::device(device),
                op::V2IP_VIDEO_WALL,
                build_video_wall(device.uid, window, op),
            ))
        })
    }

    // ---- multiviewer ----

    /// Sets the window layout.
    pub fn set_multiviewer_view_mode(
        &self,
        device: DeviceUid,
        mode: MultiviewerViewMode,
    ) -> Result<(), ControlError> {
        let mode = mv_setting(mode.to_wire(), 8, "the multiviewer has no such view mode")?;
        self.multiviewer(device, mv_sub::VIEW_MODE, &[mode])
    }

    /// Assigns a source to one window, counting windows from zero.
    ///
    /// A window index the multiviewer is not currently showing is refused
    /// rather than sent: firmware accepts an index one past the last window
    /// and writes through the end of the array it indexes, so the frame that
    /// would carry it is the one frame this library must never put on the
    /// wire. The bound comes from the layout in the multiviewer's last status
    /// report, so a multiviewer that has reported none can only be given
    /// window zero, which every layout has.
    pub fn set_multiviewer_video_source(
        &self,
        device: DeviceUid,
        screen: u8,
        source: MultiviewerSource,
    ) -> Result<(), ControlError> {
        let source = source_index(source, "the source names no multiviewer input")?;
        self.shared.command(|state| {
            let target = multiviewer_of(state, device)?;
            let windows = target
                .multiviewer
                .as_ref()
                .and_then(MultiviewerStatus::window_count)
                .unwrap_or(1);
            if screen >= windows {
                return Err(ControlError::InvalidRequest(
                    "the window is not one the multiviewer is showing",
                ));
            }
            Ok(mv_command(target, mv_sub::VIDEO_SOURCE, &[screen, source]))
        })
    }

    /// Selects which window's audio is output.
    pub fn set_multiviewer_audio_source(
        &self,
        device: DeviceUid,
        source: MultiviewerSource,
    ) -> Result<(), ControlError> {
        let source = source_index(source, "the audio source names no multiviewer input")?;
        self.multiviewer(device, mv_sub::AUDIO_SOURCE, &[source])
    }

    /// Sets the output volume, as a percentage, and the mute state.
    ///
    /// A volume above 100 is refused rather than sent. What a multiviewer does
    /// with one depends on its module version: from 2026083100 it drops the
    /// whole frame, and before that it dropped the volume alone and still
    /// acted on the mute beside it. Neither is what the caller asked for, and
    /// neither is reported back.
    pub fn set_multiviewer_audio_volume(
        &self,
        device: DeviceUid,
        volume: u8,
        muted: bool,
    ) -> Result<(), ControlError> {
        if volume > 100 {
            return Err(ControlError::InvalidRequest(
                "a multiviewer volume is a percentage",
            ));
        }
        self.multiviewer(device, mv_sub::AUDIO_VOLUME, &[volume, u8::from(muted)])
    }

    /// Sets the EDID template presented to the sources.
    pub fn set_multiviewer_edid_template(
        &self,
        device: DeviceUid,
        template: MultiviewerEdidTemplate,
    ) -> Result<(), ControlError> {
        let template = mv_setting(
            template.to_wire(),
            19,
            "the multiviewer has no such EDID template",
        )?;
        self.multiviewer(device, mv_sub::EDID_TEMPLATE, &[template])
    }

    /// Selects which window receives remote-control passthrough.
    pub fn set_multiviewer_remote_control(
        &self,
        device: DeviceUid,
        source: MultiviewerSource,
    ) -> Result<(), ControlError> {
        let source = source_index(
            source,
            "the remote-control source names no multiviewer input",
        )?;
        self.multiviewer(device, mv_sub::ROUTE_RC, &[source])
    }

    /// Sets how large the picture-in-picture window is.
    pub fn set_multiviewer_pip_size(
        &self,
        device: DeviceUid,
        size: MultiviewerPipSize,
    ) -> Result<(), ControlError> {
        let size = mv_setting(
            size.to_wire(),
            3,
            "the multiviewer has no such picture-in-picture size",
        )?;
        self.multiviewer(device, mv_sub::PIP_SIZE, &[size])
    }

    /// Sets which corner the picture-in-picture window sits in.
    pub fn set_multiviewer_pip_position(
        &self,
        device: DeviceUid,
        position: MultiviewerPipPosition,
    ) -> Result<(), ControlError> {
        let position = mv_setting(
            position.to_wire(),
            4,
            "the multiviewer has no such picture-in-picture position",
        )?;
        self.multiviewer(device, mv_sub::PIP_POSITION, &[position])
    }

    /// Sets the aspect ratio the windows are scaled to.
    pub fn set_multiviewer_aspect_ratio(
        &self,
        device: DeviceUid,
        aspect: MultiviewerAspectRatio,
    ) -> Result<(), ControlError> {
        let aspect = mv_setting(
            aspect.to_wire(),
            2,
            "the multiviewer has no such aspect ratio",
        )?;
        self.multiviewer(device, mv_sub::ASPECT, &[aspect])
    }

    /// Enables or disables switching windows on its own.
    pub fn set_multiviewer_auto_switch(
        &self,
        device: DeviceUid,
        enable: bool,
    ) -> Result<(), ControlError> {
        self.multiviewer(device, mv_sub::AUTO_SWITCH, &[u8::from(enable)])
    }

    /// Sets the output resolution and refresh rate.
    pub fn set_multiviewer_output_mode(
        &self,
        device: DeviceUid,
        mode: MultiviewerOutputMode,
    ) -> Result<(), ControlError> {
        let mode = mv_setting(
            mode.to_wire(),
            14,
            "the multiviewer has no such output mode",
        )?;
        self.multiviewer(device, mv_sub::OUTPUT_MODE, &[mode])
    }

    /// Sets the IT-content flag on the output.
    pub fn set_multiviewer_output_itc(
        &self,
        device: DeviceUid,
        mode: MultiviewerItcMode,
    ) -> Result<(), ControlError> {
        let mode = mv_setting(
            mode.to_wire(),
            2,
            "the multiviewer has no such IT-content mode",
        )?;
        self.multiviewer(device, mv_sub::OUTPUT_ITC_MODE, &[mode])
    }

    /// Sets the HDCP version negotiated on the output.
    pub fn set_multiviewer_hdcp_mode(
        &self,
        device: DeviceUid,
        mode: MultiviewerHdcpMode,
    ) -> Result<(), ControlError> {
        let mode = mv_setting(mode.to_wire(), 3, "the multiviewer has no such HDCP mode")?;
        self.multiviewer(device, mv_sub::HDCP_MODE, &[mode])
    }

    /// Maps a source device onto one of the multiviewer's inputs, counting
    /// inputs from zero.
    ///
    /// [`DeviceUid::ZERO`] clears the mapping on a multiviewer running module
    /// version 2026083100 or newer, and is stored as a mapping like any other
    /// on anything older. No version checks that a mapping names a device on
    /// the mesh.
    ///
    /// Which of the two happened shows in `mappings` on a later status report,
    /// where a cleared input reads as [`DeviceUid::ZERO`] only from that same
    /// version. It will not be the next frame this multiviewer sends: this is
    /// one of the two settings that schedule no status broadcast of their own,
    /// so the answer arrives whenever something else prompts one.
    pub fn set_multiviewer_input_source(
        &self,
        device: DeviceUid,
        input: u8,
        source: DeviceUid,
    ) -> Result<(), ControlError> {
        if usize::from(input) >= MULTIVIEWER_INPUTS {
            return Err(ControlError::InvalidRequest(
                "the multiviewer has no such input",
            ));
        }
        let mut args = Vec::with_capacity(24);
        args.extend_from_slice(source.as_bytes());
        args.push(input);
        // The body is 8-aligned, so seven bytes of padding round the uid and
        // the input index up to 24.
        args.extend_from_slice(&[0; 7]);
        self.multiviewer(device, mv_sub::CONFIG_SOURCE, &args)
    }

    /// Asks the multiviewer to route its sources itself.
    pub fn multiviewer_auto_route(&self, device: DeviceUid) -> Result<(), ControlError> {
        self.multiviewer(device, mv_sub::AUTO_ROUTE, &[])
    }

    fn multiviewer(&self, device: DeviceUid, sub: u8, args: &[u8]) -> Result<(), ControlError> {
        self.shared
            .command(|state| Ok(mv_command(multiviewer_of(state, device)?, sub, args)))
    }
}

/// The settings that switch a OneIP device's power save on or off. On is both
/// [`POWER_SAVE_DISABLED`](V2ipDeviceSetting::POWER_SAVE_DISABLED), clear, and
/// [`POWER_SAVE_LEVEL`](V2ipDeviceSetting::POWER_SAVE_LEVEL), at 0.
fn power_save_switch(enabled: bool) -> V2ipDeviceSettings {
    let disabled = V2ipDeviceSetting::POWER_SAVE_DISABLED;
    if enabled {
        V2ipDeviceSettings {
            valid: disabled | V2ipDeviceSetting::POWER_SAVE_LEVEL,
            power_save_level: V2ipPowerSaveLevel::NONE,
            ..V2ipDeviceSettings::default()
        }
    } else {
        V2ipDeviceSettings {
            valid: disabled,
            flags: disabled,
            ..V2ipDeviceSettings::default()
        }
    }
}