Skip to main content

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

Initiates a control transfer via USB

Availability

Device
imp005 and impC001 only

Parameters

Name Type Description
speed Float The speed in Mb/s. Must be either 1.5 or 12
deviceAddress Integer The address of the device
endpointAddress Integer The address of the endpoint
requestType Integer (bitfield) The type of the request
request Integer The specific USB request
value Integer A value determined by the specific USB request (range 0x0000-0xFFFF)
index Integer An index value determined by the specific USB request (range 0x0000-0xFFFF)
maxPacketSize Integer The maximum size of packet that can be written or read on this endpoint
data Blob Optional storage for incoming or outgoing data

Returns

Nothing

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.