#include <cc2511_types.h>

Data Structures
union	USB_SETUP_PACKET

struct	USB_DESCRIPTOR_DEVICE

struct	USB_DESCRIPTOR_CONFIGURATION

struct	USB_DESCRIPTOR_INTERFACE_ASSOCIATION

struct	USB_DESCRIPTOR_INTERFACE

struct	USB_DESCRIPTOR_ENDPOINT

Macros
#define	USB_VENDOR_ID_POLOLU 0x1FFB

#define	USB_EP0_PACKET_SIZE 32

#define	USB_REQUEST_GET_STATUS 0u

#define	USB_REQUEST_CLEAR_FEATURE 1u

#define	USB_REQUEST_SET_FEATURE 3u

#define	USB_REQUEST_SET_ADDRESS 5u

#define	USB_REQUEST_GET_DESCRIPTOR 6u

#define	USB_REQUEST_SET_DESCRIPTOR 7u

#define	USB_REQUEST_GET_CONFIGURATION 8u

#define	USB_REQUEST_SET_CONFIGURATION 9u

#define	USB_REQUEST_GET_INTERFACE 10u

#define	USB_REQUEST_SET_INTERFACE 11u

#define	USB_REQUEST_SYNCH_FRAME 12u

#define	USB_REQUEST_TYPE_STANDARD 0u

#define	USB_REQUEST_TYPE_CLASS 1u

#define	USB_REQUEST_TYPE_VENDOR 2u

#define	USB_RECIPIENT_DEVICE 0u

#define	USB_RECIPIENT_INTERFACE 1u

#define	USB_RECIPIENT_ENDPOINT 2u

#define	USB_RECIPIENT_OTHER 3u

#define	USB_DESCRIPTOR_TYPE_DEVICE 1u

#define	USB_DESCRIPTOR_TYPE_CONFIGURATION 2u

#define	USB_DESCRIPTOR_TYPE_STRING 3u

#define	USB_DESCRIPTOR_TYPE_INTERFACE 4u

#define	USB_DESCRIPTOR_TYPE_ENDPOINT 5u

#define	USB_DESCRIPTOR_TYPE_DEVICE_QUALIFIER 6u

#define	USB_DESCRIPTOR_TYPE_OTHER_SPEED_CONFIGURATION 7u

#define	USB_DESCRIPTOR_TYPE_INTERFACE_POWER 8u

#define	USB_DESCRIPTOR_TYPE_ENDPOINT_CLASS_SPECIFIC 0x25u

#define	USB_DESCRIPTOR_TYPE_INTERFACE_ASSOCIATION 0x0Bu

#define	USB_FEATURE_DEVICE_REMOTE_WAKEUP 1u

#define	USB_FEATURE_ENDPOINT_HALT 0u

#define	USB_FEATURE_TEST_MODE 2u

#define	USB_CONFIG_ATTR_DEFAULT (1<<7)

#define	USB_CONFIG_ATTR_SELF_POWERED (1<<6)

#define	USB_CONFIG_ATTR_REMOTE_WAKEUP (1<<5)

#define	USB_OUT 0u

#define	USB_IN 1u

#define	USB_ENDPOINT_ADDRESS_IN 0x80

#define	USB_ENDPOINT_ADDRESS_OUT 0x00

#define	USB_TRANSFER_TYPE_CONTROL 0

#define	USB_TRANSFER_TYPE_ISOCHRONOUS 1

#define	USB_TRANSFER_TYPE_BULK 2

#define	USB_TRANSFER_TYPE_INTERRUPT 3

#define	USB_LANGUAGE_EN_US 0x0409

#define	USBCSOL_OUTPKT_RDY 0x01

#define	USBCSIL_INPKT_RDY 0x01

#define	USBCSIL_PKT_PRESENT 0x02

#define	DEFINE_STRING_DESCRIPTOR(name, char_count, ...) static uint16 CODE name[] = { (2*(char_count+1)) \| (USB_DESCRIPTOR_TYPE_STRING<<8), __VA_ARGS__ };

Typedefs
typedef struct USB_DESCRIPTOR_DEVICE	USB_DESCRIPTOR_DEVICE

typedef struct USB_DESCRIPTOR_CONFIGURATION	USB_DESCRIPTOR_CONFIGURATION

typedef struct USB_DESCRIPTOR_INTERFACE_ASSOCIATION	USB_DESCRIPTOR_INTERFACE_ASSOCIATION

typedef struct USB_DESCRIPTOR_INTERFACE	USB_DESCRIPTOR_INTERFACE

typedef struct USB_DESCRIPTOR_ENDPOINT	USB_DESCRIPTOR_ENDPOINT

Enumerations
enum	USB_DEVICE_STATES { USB_STATE_DETACHED = 0, USB_STATE_ATTACHED = 1, USB_STATE_POWERED = 2, USB_STATE_DEFAULT = 4, USB_STATE_ADDRESS = 8, USB_STATE_CONFIGURED = 16 }

Functions
void	usbInit (void)

void	usbPoll (void)

void	usbControlRead (uint16 bytesCount, uint8 XDATA *source)

void	usbControlWrite (uint16 bytesCount, uint8 XDATA *source)

void	usbControlAcknowledge (void)

void	usbControlStall (void)

void	usbInitEndpointIn (uint8 endpointNumber, uint8 maxPacketSize)

void	usbInitEndpointOut (uint8 endpointNumber, uint8 maxPacketSize)

void	usbWriteFifo (uint8 endpointNumber, uint8 count, const uint8 XDATA *buffer)

void	usbReadFifo (uint8 endpointNumber, uint8 count, uint8 XDATA *buffer)

BIT	usbSuspended (void)

void	usbSleep (void)

void	usbShowStatusWithGreenLed (void)

void	usbCallbackSetupHandler (void)

void	usbCallbackClassDescriptorHandler (void)

void	usbCallbackInitEndpoints (void)

void	usbCallbackControlWriteHandler (void)

Variables
enum USB_DEVICE_STATES XDATA	usbDeviceState

USB_SETUP_PACKET XDATA	usbSetupPacket

volatile BIT	usbSuspendMode

volatile BIT	usbActivityFlag

USB_DESCRIPTOR_DEVICE CODE	usbDeviceDescriptor

uint8 CODE	usbStringDescriptorCount

uint16 CODE *CODE	usbStringDescriptors []

Detailed Description

The usb.lib library takes care of setting up the USB module and responding to standard device requests. This is a general purpose library that can be used to implement many different kinds of USB device interfaces.

If you are looking for a simple way to send and receive bytes over USB, please see usb_com.h.

Many of the constants defined here come from the USB 2.0 Specification. In particular:

The USB_RECIPIENT_* defines come from Table 9-2.
The USB_REQUEST_TYPE_* defines come from Table 9-2.
The other USB_REQUEST_* defines come from Table 9-4.
The USB_DESCRIPTOR_TYPE_* defines come from Table 9-5.
The USB_FEATURE_* defines come from Table 9-6.
The USB_CONFIG_ATTR_* defines come from Table 9-10.
The USB_TRANSFER_TYPE_* defines come from Table 9-13.

Definition in file usb.h.

Macro Definition Documentation

#define DEFINE_STRING_DESCRIPTOR	(	name,
		char_count,
		...
	)	static uint16 CODE name[] = { (2*(char_count+1)) \| (USB_DESCRIPTOR_TYPE_STRING<<8), __VA_ARGS__ };

Defines a new USB string descriptor.

Parameters

name	The variable name to use for the string descriptor.
char_count	The number of characters in the string.

This macro evaluates to a line of C code that defines a static uint16 array in CODE space with the specified name.

See the usb_cdc_acm.c for an example use.

Definition at line 230 of file usb.h.

#define USB_EP0_PACKET_SIZE 32

The maximum size of the data packets sent and received on Endpoint 0 for control transfers.

Definition at line 34 of file usb.h.

#define USB_LANGUAGE_EN_US 0x0409

The USB language ID for English (US). It comes from http://www.usb.org/developers/docs/USB_LANGIDs.pdf

Definition at line 113 of file usb.h.

#define USB_VENDOR_ID_POLOLU 0x1FFB

This is the Vendor ID assigned to Pololu Corporation by the USB Implementers Forum (USB-IF). For information on getting your own Vendor ID, see http://www.usb.org/developers/vendor/

Definition at line 30 of file usb.h.

Typedef Documentation

typedef struct USB_DESCRIPTOR_CONFIGURATION USB_DESCRIPTOR_CONFIGURATION

Standard Configuration Descriptor from USB Spec Table 9-10

typedef struct USB_DESCRIPTOR_DEVICE USB_DESCRIPTOR_DEVICE

Standard Device Descriptor from USB Spec Table 9-8.

typedef struct USB_DESCRIPTOR_ENDPOINT USB_DESCRIPTOR_ENDPOINT

Standard Endpoint Descriptor from USB Spec Table 9-13.

typedef struct USB_DESCRIPTOR_INTERFACE USB_DESCRIPTOR_INTERFACE

Standard Interface Descriptor from USB Spec Table 9-12.

typedef struct USB_DESCRIPTOR_INTERFACE_ASSOCIATION USB_DESCRIPTOR_INTERFACE_ASSOCIATION

Interface Association Descriptor. This was defined in Engineering Change Notice (ECN) #7, Table 9-Z, not the USB specification.

Enumeration Type Documentation

enum USB_DEVICE_STATES

This enum represents the different USB states defined in Section 9.1 of the USB specification.

Definition at line 40 of file usb.h.

Function Documentation

void usbCallbackClassDescriptorHandler ( void )

This is called by usbPoll() for certain Get Descriptor requests that are not supported by the USB library.

This callback is only called if bmRequest and bRequest indicate a standard Get Descriptor request, so there is no need to check those fields in this callback.

This function should read usbSetupPacket. If it recognizes the Get Descriptor request, it should call usbControlRead(). If it does not recognize the request, it should simply return. In this case, the USB library will respond to the host with a STALL packet.

This function must be defined by higher-level code. See usb_hid.c for an example.

Definition at line 271 of file usb_cdc_acm.c.

void usbCallbackControlWriteHandler ( void )

This is called by usbPoll() when all the data for a Control Write request has been received.

This function should look at the data, perform any actions necessary, and decide whether the data was valid. If the data is invaild, this function can call usbControlStall() to reject the request.

Definition at line 281 of file usb_cdc_acm.c.

void usbCallbackInitEndpoints ( void )

This is called by usbPoll() when the device enters the Configured state. This function should call usbInitEndpointIn() and usbInitEndpointOut() to initialize all the non-zero endpoints that it uses.

This function must be defined by higher-level code. See usb_cdc_acm.c for an example.

Definition at line 234 of file usb_cdc_acm.c.

void usbCallbackSetupHandler ( void )

This is called by usbPoll() whenever a new request (SETUP packet) is received from the host that can not be handled by the USB library.

This function should read usbSetupPacket. If it recognizes the request from the host it should call usbControlRead(), usbControlWrite(), or usbControlAcknowledge(). If it does not recognize the request, it should simply return. In this case, the USB library will respond to the host with a STALL packet.

This function must be defined by higher-level code. See usb_cdc_acm.c for an example.

Definition at line 246 of file usb_cdc_acm.c.

void usbControlAcknowledge ( void )

Tells the USB library to acknowledge the request. This is the right way to handle Control Write transfers with no data.

This should only be called from usbCallbackSetupHandler() or usbCallbackClassDescriptorHandler().

Definition at line 624 of file usb.c.

void usbControlRead	(	uint16	bytesCount,
		uint8 XDATA *	source
	)

Tells the USB library to start a Control Read (Device-to-Host) transfer.

Parameters

bytesCount	The number of bytes to send to the USB Host.
source	A pointer to the first byte to send.

This should only be called from usbCallbackSetupHandler() or usbCallbackClassDescriptorHandler().

Definition at line 610 of file usb.c.

void usbControlStall ( void )

Tells the USB library that the request was invalid or failed, so it should respond to the host with STALL packet.

This should only be called from usbCallbackControlWriteHandler() in order to reject a Control Write transfer after the data has been received.

It can also be used in usbCallbackSetupHandler() or usbCallbackClassDescriptorHandler(), but it is not necessary in those callbacks because the default behavior of the library in that case is to stall.

Definition at line 630 of file usb.c.

void usbControlWrite	(	uint16	bytesCount,
		uint8 XDATA *	source
	)

Tells the USB library to start a Control Write (Host-to-Device) transfer.

Parameters

bytesCount	The number of bytes to read from the host.
source	A pointer to the location that the bytes will be written to.

This should only be called from usbCallbackSetupHandler() or usbCallbackClassDescriptorHandler().

Definition at line 617 of file usb.c.

void usbInit ( void )

Initializes the USB library. This should be called before any other USB functions.

Definition at line 29 of file usb.c.

void usbInitEndpointIn	(	uint8	endpointNumber,
		uint8	maxPacketSize
	)

Configures the specified endpoint to do double-buffered IN (device-to-host) transactions.

This should only be called from usbCallbackInitEndpoints().

Definition at line 635 of file usb.c.

void usbInitEndpointOut	(	uint8	endpointNumber,
		uint8	maxPacketSize
	)

Configures the specified endpoint to do double-buffered OUT (host-to-device) transactions.

This should only be called from usbCallbackInitEndpoints().

Definition at line 642 of file usb.c.

void usbPoll ( void )

Handles any USB events that needs to be handled.

This function calls the usbCallback* functions when needed.

This function should be called regularly (more often than every 50 ms).

Definition at line 73 of file usb.c.

void usbReadFifo	(	uint8	endpointNumber,
		uint8	count,
		uint8 XDATA *	buffer
	)

Reads data from a USB FIFO and writes to the specified memory buffer. This is equivalent to reading data from the FIFO register (e.g. USBF4) one byte at a time. Please refer to the CC2511 datasheet to understand when you can and can not read data from a USB FIFO.

Definition at line 34 of file usb.c.

void usbShowStatusWithGreenLed ( void )

This function updates the green LED to reflect the current USB status. If you call this function frequently enough, then the green LED will exhibit these behaviors:

Off when USB is disconnected or if we are in USB suspend mode
On when we are connected to USB and are in the configured state (which usually means that the drivers are installed correctly), and flickering whenever there is USB activity.
Blinking with a period of 1024 ms if we are connected to USB but not in the configured state yet.

In order to make the flickering work properly, any library that directly reads or writes from USB FIFOs

Note: Calling this function will cause the USB library to have extra dependencies that it normally would not have, because this function accesses the system time and sets the green LED. You might get a linker error if those things are not available.

See usbActivityFlag for more information on the flickering.

Definition at line 13 of file green_led.c.

void usbSleep ( void )

Sleeps until we receive USB resume signaling. Uses PM1.

Example usage:

 if (usbSuspended() && !selfPowered())
 {
     // Here you must shut down anything that draws a lot of current
     // (except the USB pull-up resistor).  Power consumption during
     // suspend mode must be less than 0.5 mA or the device
     // will be out of spec (but usually nothing bad happens).
     usbSleep();
     // Here you should re-enable the things that were disabled.
 }

Definition at line 556 of file usb.c.

BIT usbSuspended ( void )

Returns 1 if we are connected to a USB bus that is suspended. Returns 0 otherwise.

You can use this to know when it is time to turn off the peripherals and go into a power-saving mode.

Definition at line 537 of file usb.c.

void usbWriteFifo	(	uint8	endpointNumber,
		uint8	count,
		const uint8 XDATA *	buffer
	)

Writes the specified data to a USB FIFO. This is equivalent to writing data to the FIFO register (e.g. USBF4) one byte at a time. Please refer to the CC2511 datasheet to understand when you can and can not write data to a USB FIFO.

Definition at line 46 of file usb.c.

Variable Documentation

volatile BIT usbActivityFlag

Libraries that directly access USB registers should set this bit to 1 whenever they read or write data from USB. This allows the USB led to flicker when there is USB activity. See usbShowStatusWithGreenLed() for more information.

Note: The USB HID library does not set this bit because that would result in constant flickering of the green LED in typical HID applications.

Definition at line 27 of file usb.c.

USB_DESCRIPTOR_DEVICE CODE usbDeviceDescriptor

The device's Device Descriptor.

This must be defined by higher-level code. See usb_cdc_acm.c for an example.

Definition at line 109 of file usb_cdc_acm.c.

enum USB_DEVICE_STATES XDATA usbDeviceState

The current USB Device State of this device.

Higher-level code should avoid reading or writing from non-zero USB endpoints if usbDeviceState is not USB_STATE_CONFIGURED because the non-zero endpoints are get initialized when the device enters the configured state.

Definition at line 18 of file usb.c.

USB_SETUP_PACKET XDATA usbSetupPacket

The value of the last setup packet received from the host. It is useful to read this in usbCallbackSetupHandler(), usbCallbackControlWriteHandler(), and usbCallbackClassDescriptorHandler().

Definition at line 17 of file usb.c.

uint8 CODE usbStringDescriptorCount

The number of string descriptors on this device.

This must be defined by higher-level code. See usb_cdc_acm.c for an example.

Definition at line 224 of file usb_cdc_acm.c.

uint16 CODE* CODE usbStringDescriptors[]

An array of pointers to the string descriptors. The first entry corresponds to string descriptor 0 (the languages). The second entry corresponds to string descriptor 1, etc.

This must be defined by higher-level code. See usb_cdc_acm.c for an example.

Definition at line 228 of file usb_cdc_acm.c.

volatile BIT usbSuspendMode

Direct access to this bit is provided for applications that need to use the P0 interrupt and want USB suspend mode to work. If you don't fall into that category, please don't use this bit directly: instead you should call usbSuspended() because that function is less likely to change in future versions. If you want to have a P0 interrupt AND USB Suspend, you should write your ISR like this:

 ISR(P0INT, 0)
 {
     // Handle the P0 flags you care about here, but you might want to
     // check PICTL first because if we are in suspend mode then the P0
     // interrupt settings may be different from what you set them to be.
 
     if (P0IFG & 0x80)  // Check USB_RESUME bit.
     {
         usbSuspendMode = 0;   // Causes usbSleep to exit sleep mode.
     }
     P0IFG = 0;   // Clear the flags so this interrupt doesn't run again.
     P0IF = 0;
 }

If your P0 ISR does NOT clear usbSuspendMode, then your device will not be able to wake up out of suspend mode because when USB activity happens, your ISR will (if it's well-written) clear P0IFG so usbSleep won't be able to see that the P0IFG.USB_RESUME bit has been set, and it will keep on sleeping.

Definition at line 24 of file usb.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation