<!-- Source: https://medius.k4tech.net/library/connection -->
# Connecting

_Open, find, and hand the box back_

A Medius box bridges a mouse and a PC over USB-serial. The `medius` crate is the Rust client and `Device` is the handle; opening one finds the box, runs the [handshake](/native/connection.md), and starts the background threads in one call.

See also: [choosing a port](/library/guides/connection.md#choosing-a-port), [threading](/library/guides/connection.md#threading), [keepalive & teardown](/library/guides/connection.md#keepalive), and the box [handshake](/native/connection.md#handshake).

## Open a device

_Auto-detect, or a path you already have_

```text
fn Device::open(path: impl AsRef<Path>) -> Result<Device>
```

_Blocks_

```text
fn Device::find() -> Result<Device>
```

_Blocks_

```text
fn Device::find_medius() -> Vec<PortInfo>
```

_No round-trip_

`open` and `find` block on the [handshake](/native/connection.md#handshake). Auto-detect matches on [USB identity](/native/transport.md) (vid `0x1A86`, pid `0x55D3`), the WCH CH343 bridge in every box.

#### FUNCTIONS

| Function | Description |
| --- | --- |
| `open` | Opens a serial path you already have (Linux `/dev/ttyACM0`, Windows `COM3`). |
| `find` | Opens the first matching port, or returns [`Error::NotFound`](/library/types/errors.md). |
| `find_medius` | Lists every match as a [`PortInfo`](/library/types/structs.md#port-info) without opening one. |

#### EXAMPLE

```rust
use medius::Device;

// auto-detect the box:
let dev = Device::find()?;

// or, open a path you already know:
let dev = Device::open("/dev/ttyACM0")?;
```

## Zero config

_No settings struct, just two defaults_

Nothing to configure; two read-only defaults bound the [`QUERY`](/native/commands/requests.md#requests) wait and keepalive timer.

| Constant | Value |
| --- | --- |
| `DEFAULT_QUERY_TIMEOUT` | `1 s` |
| `DEFAULT_KEEPALIVE_CADENCE` | `500 ms` |

#### EXAMPLE

```rust
use medius::{DEFAULT_QUERY_TIMEOUT, DEFAULT_KEEPALIVE_CADENCE};

println!("query timeout:     {:?}", DEFAULT_QUERY_TIMEOUT);   // 1s
println!("keepalive cadence: {:?}", DEFAULT_KEEPALIVE_CADENCE); // 500ms
```

## Async device

_The same link, with awaitable queries_

```text
fn AsyncDevice::open(path: impl AsRef<Path>) -> Result<AsyncDevice>
```

_Blocks_

```text
fn AsyncDevice::find() -> Result<AsyncDevice>
```

_Blocks_

```text
fn into_async(self) -> AsyncDevice
```

_No round-trip_

```text
fn into_inner(self) -> Device
```

_No round-trip_

Behind the `async` feature, [`AsyncDevice`](/library/features/async.md) turns the reply-reading queries into futures; the [fire-and-forget](/native/injection.md#fire-and-forget) calls stay synchronous. Construct one with `AsyncDevice::find`, `open` by path, or `into_async`; full surface on the async feature page.

```bash
cargo add medius --features async
```

#### EXAMPLE

```rust
use futures::executor::block_on;
use medius::AsyncDevice;

// discover and open directly as async:
let dev = AsyncDevice::find()?;
let version = block_on(dev.query_version())?; // awaits the reply
dev.move_rel(10, 0)?;                          // fire-and-forget, stays sync

// or open a path you already have:
let dev = AsyncDevice::open("/dev/ttyACM0")?;
```