1# -*- coding: utf-8 -*-
2"""High level wrapper for USB resources.
3
4This file is part of PyVISA.
5
6:copyright: 2014-2020 by PyVISA Authors, see AUTHORS for more details.
7:license: MIT, see LICENSE for more details.
8
9"""
10from .. import attributes, constants
11from ..attributes import Attribute
12from .messagebased import ControlRenMixin, MessageBasedResource
13
14
15class USBCommon(MessageBasedResource):
16    """Common class for USB resources."""
17
18    #: USB interface number used by the given session.
19    interface_number: Attribute[int] = attributes.AttrVI_ATTR_USB_INTFC_NUM()
20
21    #: USB serial number of this device.
22    serial_number: Attribute[str] = attributes.AttrVI_ATTR_USB_SERIAL_NUM()
23
24    #: USB protocol used by this USB interface.
25    usb_protocol: Attribute[int] = attributes.AttrVI_ATTR_USB_PROTOCOL()
26
27    #: Maximum size of data that will be stored by any given USB interrupt.
28    maximum_interrupt_size: Attribute[int] = attributes.AttrVI_ATTR_USB_MAX_INTR_SIZE()
29
30    #: Manufacturer name.
31    manufacturer_name: Attribute[str] = attributes.AttrVI_ATTR_MANF_NAME()
32
33    #: Manufacturer identification number of the device.
34    manufacturer_id: Attribute[int] = attributes.AttrVI_ATTR_MANF_ID()
35
36    #: Model name of the device.
37    model_name: Attribute[str] = attributes.AttrVI_ATTR_MODEL_NAME()
38
39    #: Model code for the device.
40    model_code: Attribute[int] = attributes.AttrVI_ATTR_MODEL_CODE()
41
42
43@MessageBasedResource.register(constants.InterfaceType.usb, "INSTR")
44class USBInstrument(ControlRenMixin, USBCommon):
45    """USB INSTR resources USB::manufacturer ID::model code::serial number
46
47    More complex resource names can be specified with the following grammar:
48        USB[board]::manufacturer ID::model code::serial number[::USB interface number][::INSTR]
49
50    Do not instantiate directly, use
51    :meth:`pyvisa.highlevel.ResourceManager.open_resource`.
52
53    """
54
55    #: Whether the device is 488.2 compliant.
56    is_4882_compliant: Attribute[bool] = attributes.AttrVI_ATTR_4882_COMPLIANT()
57
58    def control_in(
59        self,
60        request_type_bitmap_field: int,
61        request_id: int,
62        request_value: int,
63        index: int,
64        length: int = 0,
65    ) -> bytes:
66        """Performs a USB control pipe transfer from the device.
67
68        Parameters
69        ----------
70        request_type_bitmap_field : int
71            bmRequestType parameter of the setup stage of a USB control transfer.
72        request_id : int
73            bRequest parameter of the setup stage of a USB control transfer.
74        request_value : int
75            wValue parameter of the setup stage of a USB control transfer.
76        index : int
77            wIndex parameter of the setup stage of a USB control transfer.
78            This is usually the index of the interface or endpoint.
79        length : int
80            wLength parameter of the setup stage of a USB control transfer.
81            This value also specifies the size of the data buffer to receive
82            the data from the optional data stage of the control transfer.
83
84        Returns
85        -------
86        bytes
87            The data buffer that receives the data from the optional data stage
88            of the control transfer.
89
90        """
91        return self.visalib.usb_control_in(
92            self.session,
93            request_type_bitmap_field,
94            request_id,
95            request_value,
96            index,
97            length,
98        )[0]
99
100    def control_out(
101        self,
102        request_type_bitmap_field: int,
103        request_id: int,
104        request_value: int,
105        index: int,
106        data: bytes = b"",
107    ):
108        """Performs a USB control pipe transfer to the device.
109
110        Parameters
111        ----------
112        request_type_bitmap_field : int
113            bmRequestType parameter of the setup stage of a USB control transfer.
114        request_id : int
115            bRequest parameter of the setup stage of a USB control transfer.
116        request_value : int
117            wValue parameter of the setup stage of a USB control transfer.
118        index : int
119            wIndex parameter of the setup stage of a USB control transfer.
120            This is usually the index of the interface or endpoint.
121        data : str
122            The data buffer that sends the data in the optional data stage of
123            the control transfer.
124
125        """
126        return self.visalib.usb_control_out(
127            self.session,
128            request_type_bitmap_field,
129            request_id,
130            request_value,
131            index,
132            data,
133        )
134
135
136@MessageBasedResource.register(constants.InterfaceType.usb, "RAW")
137class USBRaw(USBCommon):
138    """USB RAW resources: USB::manufacturer ID::model code::serial number::RAW
139
140    More complex resource names can be specified with the following grammar:
141        USB[board]::manufacturer ID::model code::serial number[::USB interface number]::RAW
142
143    Do not instantiate directly, use
144    :meth:`pyvisa.highlevel.ResourceManager.open_resource`.
145
146    """
147