Skip to main content

usb.configure(callback)

Configures the imp005’s USB

Availability

Device (from impOS™ 34)
Only available on the imp005

Parameters

Name Type Description
callback Function The function that will be called in response to a USB event

Returns

Nothing

Description

This method enables the USB peripheral and registers an event callback. It takes a single parameter: a reference to a function that will be called automatically in response to USB events.

The callback function takes two parameters:

Parameter Type Description
eventType Constant The type of event that triggered the callback
eventDetails String or null Event-specific information

The value passed into eventType is constant of which there are currently four possible values:

  • USB_DEVICE_CONNECTED
  • USB_TRANSFER_COMPLETED
  • USB_DEVICE_DISCONNECTED
  • USB_UNRECOVERABLE_ERROR

Your event handler function will need to branch according to the value of eventType because each one will generate a different eventDetails table, as described below.

USB_DEVICE_CONNECTED

The eventDetails table contains the full description of the device.

Key Type Description
speed Float The speed at which the connected device operates in Mb/s. Currently will return 1.5 or 12 only.
descriptors Table The device descriptors (see below)

The descriptors table within eventDetails contains the following keys:

descriptors Keys Type Description
usb Integer The USB specification to which the device conforms.
It is a binary coded decimal value. For example, 0x0110 is USB 1.1
class Integer The USB class assigned by USB-IF. If 0x00, each interface specifies its own class. If 0xFF, the class is vendor specific. Note class is a Squirrel keyword, so this key must be accessed using index syntax (ie. descriptors["class"]) not the customary dot syntax
subclass Integer The USB subclass (assigned by the USB-IF)
protocol Integer The USB protocol (assigned by the USB-IF)
maxpacketsize Integer The maximum size of a packet to endpoint (ie. the control endpoint) in bytes
vendorid Integer The vendor ID (assigned by the USB-IF)
productid Integer The product ID (assigned by the vendor)
device Integer The device version number as BCD
manufacturer Integer Index to string descriptor containing the manufacturer string
product Integer Index to string descriptor containing the product string
serial Integer Index to string descriptor containing the serial number string
numofconfigurations Integer The number of possible configurations
configurations Array of tables The configuration descriptors (see below)

At the moment, only the first configuration on a USB_DEVICE_CONNECTED event is reported here, so the configurations key is always a single-element array containing one table. There may be other configurations available: check numofconfigurations to find out how many there are, including the one included in the configurations array. If numofconfigurations is greater than one, the other configurations can be obtained by issuing the appropriate control transfers directly from Squirrel.

Each configurations table contains the following keys:

configurations Key Type Description
value Integer Unique identifier for this configuration. Use this to set the configuration
configuration Integer Index to string descriptor containing the description
attributes Integer
bitfield
D0-4 — Reserved (set to 1)
D5 — Remote wakeup
D6 — Self power
D7 — Reserved (set to 1)
maxpower Integer Max power consumption in multiples of 2mA
interfaces Array of tables The interface descriptors (see below)

Each interface table contains the following keys:

interface Key Type Description
interfacenumber Integer The number representing this interface
altsetting Integer The alternative setting of this interface
class Integer The interface class. Note class is a Squirrel keyword, so this key must be accessed using index syntax (ie. interface["class"]) not the customary dot syntax
subclass Integer The interface subclass
protocol Integer The interface class protocol
interface Integer The index of the string descriptor describing this interface
endpoints Array of tables The interface descriptors (see below)

Each endpoints table contains the following keys:

endpoints Key Type Description
address Integer
bitfield
The endpoint address:
D0-3 — Endpoint number
D4-6 — Reserved
D7 — Direction (0 out, 1 in)
attributes Integer
bitfield
D0-1 — Transfer type:
00: control
01: isochronous
10: bulk
11: interrupt
Remaining bits are for isochronous mode which is not yet supported
maxpacketsize Integer The maximum size of packet this endpoint can send or receive
interval Integer Only relevant for isochronous endpoints (not yet supported)

USB_DEVICE_DISCONNECTED

The eventDetails table contains just the device address, provided via the key device.

USB_TRANSFER_COMPLETED

The eventDetails table contains the information needed to identify which transfer has completed.

Field Type Description
device Integer The address of the device
interface Integer The interface
endpoint Integer The endpoint address
type Integer The endpoint type (bulk, etc)
state Integer The completion code of the transfer
length Integer The amount of data (bytes) that was written or read

Note You should check explicitly the numeric value of state. The following table lists the meaning of the possible values to which state may be set. These values are not yet provided as symbolic constants:

state value Meaning
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

Not all of the non-zero state values indicate errors. For example, USB_TYPE_FREE (15) and USB_TYPE_IDLE (16) are not errors. The range of possible error values you may encounter will depend on which type of USB device you are connecting.

A state of USB_TYPE_STALL_ERROR (4) can be dealt with by following the procedure described in the guide ‘Understanding USB Errors’. Other errors can be dealt with by resetting the bus: call usb.disable() and then usb.configure() once again.

USB_UNRECOVERABLE_ERROR

This event is caused by an internal hardware error and is unrecoverable. Such errors can be dealt with by resetting the bus: call usb.disable() and then usb.configure() once again.

For more information on USB errors, please see the guide ‘Understanding USB Errors’.

Example Code

The following code provides a vary basic foundation for a USB support mechanism within your device code. It registers a function that will be automatically called in response to a USB event. It looks for three USB events: USB_DEVICE_CONNECTED, USB_DEVICE_DISCONNECTED and USB_TRANSFER_COMPLETED. In the case of the first of these, the code attempts to load a driver by calling a second function which checks the device’s vendor and product IDs to load in an appropriate driver class (if available).