Configures the imp’s USB
Device
imp005 and impC001 only
| Name | Type | Description |
|---|---|---|
| callback | Function |
The function that will be called in response to a USB event
|
Nothing
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 | Table or null |
Event-specific information |
The value passed into eventType is constant of which there are currently four possible values:
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.
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) |
| maxpacketsize0 | Integer | The maximum size of a packet to endpoint 0 (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) |
The eventDetails table contains just the device address, provided via the key device.
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.
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.
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).