USB Transport
=============

Overview
--------

USB-connected ANURA transceivers (such as the TR11) expose the Transceiver API over a USB transport.
This transport provides direct, low-latency communication over USB bulk endpoints.

Device Identification
---------------------

.. list-table::
   :header-rows: 1

   * - Parameter
     - Value
   * - Vendor ID (VID)
     - ``0x16D0``
   * - Product ID (PID)
     - ``0x13D4``
   * - Device Class
     - Vendor-specific
   * - Configuration
     - 1 (default)
   * - Interface
     - 0

Clients should enumerate USB devices and match against these VID/PID values to identify ANURA transceivers.

Endpoints
---------

The transceiver uses two bulk endpoints for bidirectional communication:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Endpoint
     - Description
   * - ``0x01`` (OUT)
     - Host to device (client sends requests to transceiver)
   * - ``0x81`` (IN)
     - Device to host (transceiver sends responses and notifications to client)

Both endpoints operate as bulk transfer endpoints for efficient data streaming.

Message Framing
---------------

CBOR-RPC messages are transmitted over USB bulk endpoints with the same length-prefixed framing protocol used by the TCP transport:

1. **Length Prefix**: Each message begins with a 16-bit unsigned integer in big-endian byte order, indicating the length of the following CBOR payload in bytes.
2. **CBOR Payload**: Immediately following the length prefix is the CBOR-encoded message payload.

The maximum message size supported by the framing protocol is 65,535 bytes (2¹⁶ - 1).
In practice, this is further limited by device-specific constraints.

Framing Format
^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1

   * - Field
     - Size
     - Description
   * - Length
     - 2 bytes
     - Big-endian uint16 indicating payload length
   * - Payload
     - N bytes
     - CBOR-encoded message (N = value of Length field)

Communication Flow
------------------

1. **Enumerate Device**: Client enumerates USB devices and identifies the transceiver by VID/PID.
2. **Open Device**: Client opens the USB device and claims interface 0.
3. **Exchange Messages**: Client and transceiver exchange length-prefixed CBOR-RPC messages bidirectionally. The client writes messages to endpoint ``0x01`` (OUT) and reads messages from endpoint ``0x81`` (IN).
4. **Close Device**: Client releases the interface and closes the USB device when done.

The client must continuously read from the IN endpoint to receive responses and asynchronous notifications, demultiplexing them based on message type and request token.

Example Message Frame
---------------------

Consider a simple request to call the :cborrpc:meth:`ping` method:

**CBOR Message**: ``[0, 1, "ping", null]``

**Encoded CBOR** (hexadecimal): ``84 00 01 64 70 69 6E 67 F6``

**Complete TCP Frame**:

.. list-table::
   :widths: 40 60
   :header-rows: 1

   * - Data (hexadecimal)
     - Description
   * - ``00 09``
     - Payload Length (big-endian): 0009h = 9 bytes
   * - ``84 00 01 64 70 69 6E 67 F6``
     - CBOR Payload: ``[0, 1, "ping", null]``

This frame would be written to endpoint ``0x01`` (OUT) via a USB bulk transfer.

Implementation Notes
--------------------

- USB bulk transfers may be split across multiple USB packets at the USB protocol layer; the length-prefix framing operates above this layer.
- Clients should read the full 2-byte length prefix before attempting to decode the CBOR payload.
- The transceiver may send notifications asynchronously on the IN endpoint; clients must be prepared to receive data at any time.
- USB library choice varies by platform (libusb, WinUSB, IOKit, etc.). Ensure proper device permissions are configured.
- If the device is reset or disconnected, clients must re-enumerate and reopen the device.