usb.controltransfer(speed, deviceAddress, endpointAddress, requestType, request, value, index, maxPacketSize, data)

Description

When a device is first connected you can communicate with it at address 0x00. This should be set to a unique value for the device, using a set address control transfer.

If the transfer failed, the method will raise an exception, which will be one of the following errors and status codes:

Value	Error / Status Message
0	OK
1	USB_TYPE_CRC_ERROR
2	USB_TYPE_BIT_STUFFING_ERROR
3	USB_TYPE_DATA_TOGGLE_MISMATCH_ERROR
4	USB_TYPE_STALL_ERROR
5	USB_TYPE_DEVICE_NOT_RESPONDING_ERROR
6	USB_TYPE_PID_CHECK_FAILURE_ERROR
7	USB_TYPE_UNEXPECTED_PID_ERROR
8	USB_TYPE_DATA_OVERRUN_ERROR
9	USB_TYPE_DATA_UNDERRUN_ERROR
10	USB_TYPE_UNKNOWN_ERROR
11	USB_TYPE_UNKNOWN_ERROR
12	USB_TYPE_BUFFER_OVERRUN_ERROR
13	USB_TYPE_BUFFER_UNDERRUN_ERROR
14	USB_TYPE_DISCONNECTED
15	USB_TYPE_FREE
16	USB_TYPE_IDLE
17	USB_TYPE_BUSY
18	USB_TYPE_INVALID_ENDPOINT
19	USB_TYPE_TIMEOUT
20	USB_TYPE_INTERNAL_ERROR

• For more information on determining the source of USB errors and implementing recovery methods, please see Understanding USB Errors.

Possible values of the usb.controltransfer() method’s requestType parameter are as follows. Note you will need to pass the numeric value — these are not yet provided as symbolic constants.

Request Type Constant	Value	Description
USB_SETUP_HOST_TO_DEVICE	0x00	Transfer direction: host to device
USB_SETUP_DEVICE_TO_HOST	0x80	Transfer direction: device to host
USB_SETUP_TYPE_STANDARD	0x00	Type: standard
USB_SETUP_TYPE_CLASS	0x20	Type: class
USB_SETUP_TYPE_VENDOR	0x40	Type: vendor
USB_SETUP_RECIPIENT_DEVICE	0x00	Recipient: device
USB_SETUP_RECIPIENT_INTERFACE	0x01	Recipient: interface
USB_SETUP_RECIPIENT_ENDPOINT	0x02	Recipient: endpoint
USB_SETUP_RECIPIENT_OTHER	0x03	Recipient: other

Possible values of the request parameter are as follows. Note you will need to pass the numeric value — these are not yet provided as symbolic constants.

Request Type Constant	Value	USB Request
USB_REQUEST_GET_STATUS	0	Get status
USB_REQUEST_CLEAR_FEATURE	1	Clear feature
USB_REQUEST_SET_FEATURE	3	Set feature
USB_REQUEST_SET_ADDRESS	5	Set address
USB_REQUEST_GET_DESCRIPTOR	6	Get descriptor
USB_REQUEST_SET_DESCRIPTOR	7	Set descriptor
USB_REQUEST_GET_CONFIGURATION	8	Get configuration
USB_REQUEST_SET_CONFIGURATION	9	Set configuration
USB_REQUEST_GET_INTERFACE	10	Get interface
USB_REQUEST_SET_INTERFACE	11	Set interface
USB_REQUEST_SYNCH_FRAME	12	Sync frame

The parameter value should take an integer of up to two bytes in size indicating the specific request values. For example, in the USB_REQUEST_GET_DESCRIPTOR request, the value indicates the descriptor type; in the USB_REQUEST_SET_ADDRESS request, the value contains the device address.

The index parameter is an integer (up to two bytes) and takes a request-specific index. The index is generally used to specify an endpoint or an interface.

The maximum size of packet that can be written or read on this endpoint is provided in the endpoint descriptor returned to the callback function registered with usb.configure() when the peripheral device first connects.

The data parameter is optional. If included, it should be a blob. For an outbound transfer, this blob can be pre-populated with the relevant output data. The size of the blob must be the size of the write data. For an inbound transfer, the blob should be empty but pre-sized to the required number of bytes for the transfer.