Functions
usb.c File Reference

Detailed Description

Contains APIs related to handling of Control Endpoint.

Functions

BYTE USB_init (VOID)
BYTE USB_setup (BYTE connectEnable, BYTE eventsEnable)
BYTE USB_enable ()
BYTE USB_enable_crystal (void)
void USB_enable_PLL (void)
void USB_enable_final (void)
BYTE USB_disable (VOID)
BYTE USB_setEnabledEvents (WORD events)
WORD USB_getEnabledEvents ()
BYTE USB_reset ()
BYTE USB_connect ()
BYTE USB_disconnect ()
BYTE USB_forceRemoteWakeup ()
BYTE USB_connectionInfo ()
BYTE USB_connectionState ()

Function Documentation

BYTE USB_init ( VOID  )

Initializes the USB Module.

Initializes the USB module by configuring power and clocks, and configures pins that are critical for USB. This should be called very soon after the beginning of program execution.

Note that this does not enable the USB module (that is, does not set USB_EN bit). Rather, it prepares the USB module to detect the application of power to VBUS, after which the application may choose to enable the module and connect to USB. Calling this function is necessary to achieve expected LPM3 current consumption into DVCC.

Returns:
kUSB_succeed

Referenced by USB_setup().

BYTE USB_setup ( BYTE  connectEnable,
BYTE  eventsEnable 
)

Initializes the USB Module. Also enables events and connects.

Initializes the USB module by configuring power and clocks, and configures pins that are critical for USB. This should be called very soon after the beginning of program execution.

If connectEnable is TRUE, then this API then enables the USB module, which includes activating the PLL and setting the USB_EN bit. AFter enabling the USB module, this API will connect to the host if VBUS is present.

If eventsEnable is set to TRUE then all USB events are enabled by this API.

Parameters:
connectEnableIf TRUE, Connect to host if VBUS is present by pulling the D+ signal high using the PUR pin.
eventsEnableIf TRUE, all USB events handlers are enabled
Returns:
kUSB_succeed
BYTE USB_enable ( )

Enables the USB Module.

Enables the USB module, which includes activating the PLL and setting the USB_EN bit. Power consumption increases as a result of this operation (see device datasheet for specifics). This call should only be made after an earlier call to USB_init(), and prior to any other call except than USB_setEnabledEvents(), or USB_getEnabledEvents(). It is usually called just prior to attempting to connect with a host after a bus connection has already been detected.

Returns:
kUSB_succeed

Referenced by USB_handleVbusOnEvent(), and USB_setup().

BYTE USB_enable_crystal ( void  )

First phase of enabling the USB Module when USE_TIMER_FOR_RESUME is defined

This functions is only used by USB_resume to reduce the interrupt latency of the resume interrupt. This function starts the XT2 crystal and then calls an event handler USB_handleCrystalStartedEvent() to allow the application to get control. The application can use a timer or other peripheral to "wait" for the XT2 crystal to stabilize. See the crystal datasheet for typical wait times. The application then informs the stack of XT2 stabilization by calling USB_enable_PLL().

Returns:
kUSB_succeed or kUSB_generalError
void USB_enable_PLL ( void  )

Second phase of enabling the USB Module when USE_TIMER_FOR_RESUME is defined

This functions is only used by USB_resume to reduce the interrupt latency of the resume interrupt. This function starts the PLL and then calls an event handler USB_handlePLLStartedEvent() to allow the application to get control. The application can use a timer or other peripheral to "wait" for the USB PLL to stabilize. See the datasheet for typical PLL wait times. The application then informs the stack of XT2 stabilization by calling USB_enable_final().

Returns:
kUSB_succeed or kUSB_generalError
void USB_enable_final ( void  )

Final phase of enabling the USB Module when USE_TIMER_FOR_RESUME is defined

This function is only used by USB_resume to reduce the interrupt latency of the resume interrupt. This function gets called by the application when thye USB PLL has stabilized to allow the resume process to finish.

BYTE USB_disable ( VOID  )

Disables the USB Module and PLL.

Disables the USB module and PLL. If USB is not enabled when this call is made, no error is returned - the call simply exits with success.

If a handleVbusOffEvent() occurs, or if USB_connectionState() begins returning ST_USB_DISCONNECTED, this function should be called (following a call to USB_disconnect()), in order to avoid unnecessary current draw.

Returns:
kUSB_succeed

Referenced by USB_handleClockEvent().

BYTE USB_setEnabledEvents ( WORD  events)

Enables/Disables the Various USB Events.

Parameters:
eventsis the mask for what is to be enabled/disabled.
  • Valid values are:
    • kUSB_clockFaultEvent
    • kUSB_VbusOnEvent
    • kUSB_VbusOffEvent
    • kUSB_UsbResetEvent
    • kUSB_UsbSuspendEvent
    • kUSB_UsbResumeEvent
    • kUSBCDC_dataReceivedEvent
    • kUSBCDC_sendCompletedEvent
    • kUSBCDC_receiveCompletedEvent
    • kUSBHID_dataReceivedEvent
    • kUSBHID_sendCompletedEvent
    • kUSBHID_receiveCompletedEvent
    • kUSB_allUsbEvents

Enables/disables various USB events. Within the events byte, all bits with '1' values will be enabled, and all bits with '0' values will be disabled. (There are no bit-wise operations). By default (that is, prior to any call to this function), all events are disabled.

The status of event enabling can be read with the USB_getEnabledEvents() function. This call can be made at any time after a call to USB_init().

USB_setEnabledEvents() can be thought of in a similar fashion to setting/clearing interrupt enable bits. The only benefit in keeping an event disabled is to save the unnecessary execution cycles incurred from running an "empty" event handler.

The mask constant kUSB_allUsbEvents is used to enable/disable all events pertaining to core USB functions; in other words, it enables all those with a kUSB_ prefix.

See Sec. 10 of "Programmer's Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" for more information about events.

Returns:
kUSB_succeed

Referenced by USB_setup().

WORD USB_getEnabledEvents ( )

Returns Which Events are Enabled/Disabled.

Returns which events are enabled and which are disabled. The definition of events is the same as for USB_enableEvents() above.

If the bit is set, the event is enabled. If cleared, the event is disabled. By default (that is, prior to calling USB_setEnabledEvents() ), all events are disabled. This call can be made at any time after a call to USB_init().

Returns:
Events
BYTE USB_reset ( )

Resets the USB Module and the Internal State of the API.

Resets the USB module and also the internal state of the API. The interrupt register is cleared to make sure no interrupts are pending. If the device had been enumerated, the enumeration is now lost. All open send/receive operations are aborted.

This function is most often called immediately before a call to USB_connect(). It should not be called prior to USB_enable().

Returns:
kUSB_succeed

Referenced by USB_handleVbusOnEvent(), and USB_setup().

BYTE USB_connect ( )

Makes USB Module Available to Host for Connection.

Instructs the USB module to make itself available to the host for connection, by pulling the D+ signal high using the PUR pin. This call should only be made after a call to USB_enable().

Returns:
kUSB_succeed

Referenced by USB_handleVbusOnEvent(), and USB_setup().

BYTE USB_disconnect ( )

Forces a Disconnect From the USB Host.

Forces a logical disconnect from the USB host by pulling the PUR pin low, removing the pullup on the D+ signal. The USB module and PLL remain enabled. If the USB is not connected when this call is made, no error is returned - the call simply exits with success after ensuring PUR is low.

Returns:
kUSB_succeed

Referenced by USB_handleClockEvent().

BYTE USB_forceRemoteWakeup ( )

Remote Wakeup of USB Host.

Prompts a remote wakeup of the USB host. The user must ensure that the USB descriptors had indicated remote wakeup capability (using the Descriptor Tool); otherwise the host will ignore the request.

If the function returns kUSB_generalError, it means that the host did not grant the device the ability to perform a remote wakeup, when it enumerated the device.

Returns:
kUSB_succeed, kUSBgeneralError or kUSB_notSuspended.
BYTE USB_connectionInfo ( )

Gets Connection Info.

Returns low-level status information about the USB connection.

Because multiple flags can be returned, the possible values can be masked together - for example, kUSB_vbusPresent + kUSB_suspended.

Returns:
A single mask that is the all the statuses together and may consist of the following:
  • kUSB_purHigh
  • kUSB_suspended
  • kUSB_NotSuspended
  • kUSB_Enumerated
  • kUSB_vbusPresent

Referenced by USB_setup().

BYTE USB_connectionState ( )

Gets State of the USB Connection.

Returns the state of the USB connection, according to the state diagram in Sec. 6 of "Programmer's Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC".

Returns:
Any of the following:
  • ST_USB_DISCONNECTED
  • ST_USB_CONNECTED_NO_ENUM
  • ST_ENUM_IN_PROGRESS
  • ST_ENUM_ACTIVE
  • ST_ENUM_SUSPENDED
  • ST_NOENUM_SUSPENDED,
  • ST_ERROR.

Copyright 2013, Texas Instruments Incorporated