With more than one box plugged in, find just opens the first match. These calls enumerate every box and open a specific one by a stable identity, or by the kind of device it clones.

See also: connecting, choosing a port, and the box handshake.

fn list() -> Vec<BoxInfo>

Blocks

Opens each connected box in turn, handshakes, reads its Version (with the box MAC and name) and cloned DeviceInfo, then closes it, returning one BoxInfo per box.

use medius::Device;

for b in Device::list() {
    // id() is the box MAC hex; name() is its readable label; b.device displays as "VVVV:PPPP product".
    println!("{}  {}  {}  {}", b.id(), b.name(), b.device, b.port.path);
}

fn open_by_id(id: &str) -> Result<Device>

Blocks

Opens the box whose identity matches id: either the device MAC hex (from Version::mac_hex) or the CH343 serial. Returns Error::NotFound when no connected box matches.

use medius::Device;

// the MAC hex printed by Device::list(), stable across replugs:
let device = Device::open_by_id("123456789abc")?;

fn find_mouse_box() -> Result<Device>

Blocks

Opens the first box whose clone's DeviceKind is a mouse. Returns Error::NotFound if no connected box matches.

use medius::Device;

let mouse_box = Device::find_mouse_box()?;
mouse_box.move_rel(10, 0)?;

fn find_keyboard_box() -> Result<Device>

Blocks

The keyboard counterpart of find_mouse_box: opens the first box whose clone is a keyboard.

use medius::{Device, Key};

let kbd_box = Device::find_keyboard_box()?;
kbd_box.press(Key::A)?;

fn find_where(pred: impl Fn(&BoxInfo) -> bool) -> Result<Device>

Blocks

The general form the find_*_box helpers build on: opens the first box whose BoxInfo satisfies pred. Match on any field. Returns Error::NotFound when none match.

use medius::Device;

// the box cloning a Logitech device:
let device = Device::find_where(|b| b.device.vid == 0x046D)?;

One entry from Device::list, and the value find_where's predicate receives.

A box's identity is its device chip's base MAC (from Version::mac_hex) plus the CH343 adapter's serial. Serial paths renumber on replug; the identity does not, so open_by_id re-finds the same box.

Opening a box anchors reconnect to that identity. An automatic reconnect re-finds the same physical box even if the ports renumbered, and never adopts a different box that happens to be plugged in.

fn AsyncDevice::list() -> Vec<BoxInfo>

fn AsyncDevice::open_by_id(id: &str) -> Result<AsyncDevice>

fn AsyncDevice::find_mouse_box() -> Result<AsyncDevice>

fn AsyncDevice::find_keyboard_box() -> Result<AsyncDevice>

Blocks

AsyncDevice mirrors the discovery constructors; they block on the per-box handshake, like their Device counterparts. The reply-reading device_info query is the awaitable part.

use medius::AsyncDevice;

let device = AsyncDevice::find_mouse_box()?; // blocks on the handshake
let info = futures::executor::block_on(device.device_info())?; // awaits the reply