# Device and discovery

The narrative version of everything on this page — how to choose a selector,
what makes a handle stale, when to reboot — is
[The device lifecycle](../guides/lifecycle.md).

## Discovery

Answers "what is plugged in?" without opening anything: it reads USB-HID
enumeration directly, so no adapter is opened and no firmware command is sent.
Every field of a {py:obj}`~pycosmicsdk.DiscoveredDevice` is ready to use as an
`open()` argument or a filter key. `examples/blocking_api/system/list_devices.py`
is the runnable version.

```{eval-rst}
.. autofunction:: pycosmicsdk.list_devices

.. autoclass:: pycosmicsdk.DiscoveredDevice
```

## Device

The blocking handle for one open adapter.

:::{note}
The constructor signature in each class heading below is package-private —
`Device` and `AsyncDevice` are built by {py:obj}`~pycosmicsdk.Device.open` /
{py:obj}`~pycosmicsdk.AsyncDevice.open`, never by calling the class. It is
shown because autodoc reads it off the class, not because it is API.
:::

```{eval-rst}
.. autoclass:: pycosmicsdk.Device
   :special-members: __enter__, __exit__
```

## AsyncDevice

The `asyncio` twin. See [Blocking and asyncio](../asyncio.md) for how the two
relate and where they differ.

```{eval-rst}
.. autoclass:: pycosmicsdk.AsyncDevice
```