Logo
MSP430USBDevelopersPackage_5_20_06_03
Event_handling_api

Functions

uint8_t USBCDC_handleDataReceived (uint8_t intfNum)
 
uint8_t USBCDC_handleSendCompleted (uint8_t intfNum)
 
uint8_t USBCDC_handleReceiveCompleted (uint8_t intfNum)
 
void USBCDC_setCTS (uint8_t state)
 
uint8_t USBCDC_handleSetLineCoding (uint8_t intfNum, uint32_t lBaudrate)
 
uint8_t USBCDC_handleSetControlLineState (uint8_t intfNum, uint8_t lineState)
 
uint8_t USB_handleClockEvent ()
 
uint8_t USB_handleVbusOnEvent ()
 
uint8_t USB_handleVbusOffEvent ()
 
uint8_t USB_handleResetEvent ()
 
uint8_t USB_handleSuspendEvent ()
 
uint8_t USB_handleResumeEvent ()
 
uint8_t USB_handleEnumerationCompleteEvent ()
 
uint8_t USBHID_handleDataReceived (uint8_t intfNum)
 
uint8_t USBHID_handleSendCompleted (uint8_t intfNum)
 
uint8_t USBHID_handleReceiveCompleted (uint8_t intfNum)
 
uint8_t USBHID_handleBootProtocol (uint8_t protocol, uint8_t intfnum)
 
uint8_t * USBHID_handleEP0SetReport (uint8_t reportType, uint8_t reportId, uint16_t requestedLength, uint8_t intfnum)
 
uint8_t USBHID_handleEP0SetReportDataAvailable (uint8_t intfnum)
 
uint8_t * USBHID_handleEP0GetReport (uint8_t reportType, uint8_t reportId, uint16_t requestedLength, uint8_t intfnum)
 
uint8_t USBMSC_handleBufferEvent (void)
 

Detailed Description

Function Documentation

uint8_t USB_handleClockEvent ( )

USB PLL has Failed

This event signals that the output of the USB PLL has failed. This event may have occurred because XT2, the source of the PLL's reference clock, has failed or is unreliable. If this event occurs, the USB connection will likely be lost. It is best to handle it by calling USB_disconnect() and attempting a re-connection.

Since this event is associated with a change in state, it's a good practice to return TRUE so the main loop can adapt.

Returns
TRUE to keep CPU awake
uint8_t USB_handleEnumerationCompleteEvent ( )

Device has Become Enumerated

This event indicates that the device has just become enumerated. This corresponds with a state change to ST_ENUM_ACTIVE.

Since this event is associated with a change in state, it's a good practice to return TRUE so the main loop can adapt.

Returns
TRUE
uint8_t USB_handleResetEvent ( )

USB Host Issued a Reset

This event indicates that the USB host has issued a reset of this USB device. The API handles this automatically, and no action is required by the application to maintain USB operation. After handling the reset, the API calls this handling function, if enabled. In most cases there is no significant reason for the application to respond to bus resets.

Returns
TRUE
uint8_t USB_handleResumeEvent ( )

USB Host has Resumed this USB Device

This event indicates that the USB host has resumed this USB device from suspend mode. If the device is bus-powered, it is no longer restricted in the amount of power it can draw from VBUS. The API automatically re-enables any circuitry in the MSP430???s USB module that was disabled during suspend. The application can use this handler to re-enable other circuitry as well.

Since this event is associated with a change in state, it's a good practice to return TRUE so the main loop can adapt.

Returns
TRUE
uint8_t USB_handleSuspendEvent ( )

USB Host Suspends USB Device

This event indicates that the USB host has chosen to suspend this USB device after a period of active operation. It???s important that a bus-powered, suspended USB device limit its consumption of power from VBUS during this time. The API automatically shuts down USB-related circuitry inside the MSP430???s USB module. However, the application may need to shut down other circuitry drawing from VBUS. This handler is a good place to do this.

See Sec.11.1.3 of "Programmer???s Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC." for a complete discussion about handling suspend.

Returns
TRUE so that the main loop can adapt.
uint8_t USB_handleVbusOffEvent ( )

Valid Voltage Removed from VBUS

This event indicates that a valid voltage has just been removed from the VBUS pin. That is, the voltage on VBUS has transitioned from high to low.

This generally means the device has been removed from an active USB host. It might also mean the device is still physically attached to the host, but the host went into a standby mode; or it was attached to a powered hub but the host upstream from that hub became inactive. The API automatically responds to a VBUS-off event by powering down the USB module and PLL, which is the equivalent of calling USB_disable(). It then calls this handling function, if enabled.

Since this event is associated with a change in state, it's a good practice to return TRUE so the main loop can adapt.

Returns
TRUE to keep CPU awake
uint8_t USB_handleVbusOnEvent ( )

Valid Voltage Applied to VBUS

If this function gets executed, it indicates that a valid voltage has been applied to the VBUS pin; that is, the voltage on VBUS has transitioned from low to high.

This usually means the device has been attached to an active USB host. It is recommended to attempt a USB connection from this handler, as described in Sec. 6.3 of "Programmer???s Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC." events.

Returns TRUE to wake the main loop (if LPM was entered), so that it can take into account the change in state.

Returns
TRUE to keep CPU awake
uint8_t USBCDC_handleDataReceived ( uint8_t  intfNum)

Indicates Data has been Received for CDC Interface

Parameters
intfNumis which HID interface is being used.

This event indicates that data has been received for CDC interface intfNum with no receive operation underway. Effectively, the API doesn???t know what to do with this data and is asking for instructions. The application can respond by either initiating a receive operation or rejecting the data. Until one of these is performed, USB data reception cannot continue; any packets received from the USB host will be NAK???ed.

Therefore, this event should be handled quickly. A receive operation cannot be started directly out of this event, since USBCDC_receiveData() cannot be called from the event handlers. However, the handler can set a flag for main() to begin the receive operation. After this function exits, a call to USBCDC_getInterfaceStatus() for this CDC interface will return kUSBDataWaiting.

If the application is written so that a receive operation is always begun prior to data arriving from the host, this event will never occur. The software designer generally has a choice of whether to use this event as part of code flow (initiating receive operations after data is received), or to always keep a receive operation open in case data arrives. (See Sec. 11 of "Programmer???s Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" for more discussion.)

Returns
TRUE to wake up after data was received.
FALSE to not wake up
uint8_t USBCDC_handleReceiveCompleted ( uint8_t  intfNum)

Receive Operation on CDC Interface has Completed

Parameters
intfNumis which HID interface is being used.

This event indicates that a receive operation on CDC interface intfNum has just been completed, and the data is therefore available in the user buffer assigned when the call was made to USBCDC_receiveData(). If this event occurs, it means that the entire buffer is full, according to the size value that was requested.

The designer may wish to use this event to trigger another receive operation. This cannot be done directly out of this event, since USBCDC_receiveData() cannot be called from the event handlers. However, the handler can set a flag for main() to begin the operation.

Returns
FALSE to go asleep after interrupt (in the case the CPU slept before interrupt).
uint8_t USBCDC_handleSendCompleted ( uint8_t  intfNum)

Send Operation on CDC Interface has Completed

Parameters
intfNumis which HID interface is being used.

This event indicates that a send operation on CDC interface intfNum has just been completed.

In applications sending a series of data blocks, the designer may wish to use this event to trigger another send operation. This cannot be done directly out of this event, since USBCDC_sendData() cannot be called from the event handlers. However, the handler can set a flag for main() to begin the operation.

Returns
FALSE to go asleep after interrupt (in the case the CPU slept before interrupt).
uint8_t USBCDC_handleSetControlLineState ( uint8_t  intfNum,
uint8_t  lineState 
)

New Line State has been Received from the Host

Parameters
intfNumis which CDC interface is being used.
lineStateBIT0 is DTR_PRESENT(1) or DTR_NOT_PRESENT(0) BIT1 is RTS_PRESETNT(1) or RTS_NOT_PRESENT(0)

This event indicates that a SetControlLineState request has been received from the host and new values for RTS are available.

The application can use the new RTS value to flow off the uart.

Returns
FALSE to go asleep after interrupt (in the case the CPU slept before interrupt).
uint8_t USBCDC_handleSetLineCoding ( uint8_t  intfNum,
uint32_t  lBaudrate 
)

New Line Coding Parameters have been Received from the Host

Parameters
intfNumis which CDC interface is being used.
lBaudratehad COMport baud rate values such as 9600, 19200 etc

This event indicates that a SetLineCoding request has been received from the host and new values for baud rate are available.

The application can use the new baud rate value to re-configure the Uart in the case of a usb to uart bridge application.

Returns
FALSE to go asleep after interrupt (in the case the CPU slept before interrupt).
uint8_t USBHID_handleBootProtocol ( uint8_t  protocol,
uint8_t  intfnum 
)

Set_Protocol Request Received from the Host

Parameters
protocolindicates HID_BOOT_PROTOCOL or HID_REPORT_PROTOCOL
intfNumis which HID interface is being used.

This event applies to HID Traditional only. It indicates that the host has requested a change in the HID protocol ??? from Boot to Standard or Standard to Boot. An application that maintains separate reports for boot and standard protocols can switch to the appropriate report upon receiving this request. The protocol field is either HID_BOOT_PROTOCOL or HID_REPORT_PROTOCOL.

Returns
FALSE to go asleep after interrupt (in the case the CPU slept before interrupt).
TRUE to keep CPU awake
uint8_t USBHID_handleDataReceived ( uint8_t  intfNum)

Data has been Received for HID Interface

Parameters
intfNumis which HID interface is being used.

This event applies to HID-Datapipe only, as opposed to HID-Traditional. It indicates that data has been received for HID interface intfNum with no receive operation underway. Effectively, the API doesn???t know what to do with this data and is asking for instructions. The application can respond by either initiating a receive operation or rejecting the data. Until one of these is performed, USB data reception cannot continue; any packets received from the USB host will be NAK???ed.

Therefore, this event should be handled quickly. A receive operation cannot be started directly out of this event, since USBHID_receiveData() cannot be called from the event handlers. However, the handler can set a flag for main() to begin the receive operation. After this function exits, a call to USBHID_getInterfaceStatus() for this HID interface will return kUSBDataWaiting.

If the application is written so that a receive operation is always begun prior to data arriving from the host, this event will never occur. The software designer generally has a choice of whether to use this event as part of code flow (initiating receive operations after data is received), or to always keep a receive operation open in case data arrives. (See Sec. 11 of "Programmer???s Guide: MSP430 USB API Stack for CDC/PHDC/HID/MSC" more discussion.)

Returns
FALSE to go asleep after interrupt (in the case the CPU slept before interrupt).
TRUE to keep CPU awake
uint8_t* USBHID_handleEP0GetReport ( uint8_t  reportType,
uint8_t  reportId,
uint16_t  requestedLength,
uint8_t  intfnum 
)

Get_Report Request was Received from the Host

Parameters
reportTypeis either USB_REQ_HID_INPUT, USB_REQ_HID_OUTPUT or USB_REQ_HID_FEATURE
reportIdis values defined by report descriptor
requestedLengthis length of report
intfNumis which HID interface is being used.

This event indicates that a Get_Report request was received from the host. The application can supply a buffer of data that will be sent to the host. This handler is passed the reportType, reportId, the requested length as well as the interface number.

Returns
Pointer to input input/output/feature buffer.
uint8_t* USBHID_handleEP0SetReport ( uint8_t  reportType,
uint8_t  reportId,
uint16_t  requestedLength,
uint8_t  intfnum 
)

Set_Report request Received from the Host

Parameters
reportTypeis either USB_REQ_HID_INPUT, USB_REQ_HID_OUTPUT or USB_REQ_HID_FEATURE
reportIdis values defined by report descriptor
dataLengthis length of report
intfNumis which HID interface is being used.

This event indicates that a Set_Report request was received from the host. The application needs to supply a buffer to retrieve the report data that will be sent as part of this request. This handler is passed the reportType, reportId, the length of data phase as well as the interface number.

Returns
Pointer to input/output/feature Report Buffer
uint8_t USBHID_handleEP0SetReportDataAvailable ( uint8_t  intfnum)

Data as Part of Set_Report Request was Received from the Host

Parameters
intfNumis which HID interface is being used.

This event indicates that data as part of Set_Report request was received from the host. If the application supplied a buffer as part of USBHID_handleEP0SetReport, then this buffer will contain the Set Report data.

Returns
TRUE to wake up after data was received.
uint8_t USBHID_handleReceiveCompleted ( uint8_t  intfNum)

Receive Operation has been Completed

Parameters
intfNumis which HID interface is being used.

This event applies to HID-Datapipe only, as opposed to HID-Traditional. It indicates that a receive operation on HID interface intfNum has just been completed, and the data is therefore available in the user buffer assigned when the call was made to USBHID_receiveData(). If this event occurs, it means that the entire buffer is full, according to the size value that was requested.

The designer may wish to use this event to trigger another receive operation. This cannot be done directly out of this event, since USBHID_receiveData() cannot be called from the event handlers. However, the handler can set a flag for main() to begin the operation.

Returns
FALSE to go asleep after interrupt (in the case the CPU slept before interrupt).
TRUE to keep CPU awake
uint8_t USBHID_handleSendCompleted ( uint8_t  intfNum)

Send Operation on Data Interface has been Completed

Parameters
intfNumis which HID interface is being used.

This event applies to HID-Datapipe only, as opposed to HID-Traditional. It indicates that a send operation on data interface intfNum has just been completed.

In applications sending a series of large blocks of data, the designer may wish to use this event to trigger another send operation. This cannot be done directly out of this event, since USBHID_sendData() cannot be called from the event handlers. However, the handler can set a flag for main() to begin the operation.

Returns
FALSE to go asleep after interrupt (in the case the CPU slept before interrupt).
TRUE to keep CPU awake
uint8_t USBMSC_handleBufferEvent ( void  )

API Requests a Buffer

This event occurs when the API requests a buffer. Immediately prior to this, the API sets the operation field of the USBMSC_RWBuf_Info structure corresponding with the request, and also clears the low-power-mode bits of the MCU's status register to ensure the CPU remains awake to process the buffer after the event occurs.

NOTE: This means the return value of this event has no effect; the CPU will <– BECAUSE OF THIS... remain awake even if this function returns FALSE.

Returns
FALSE to go to sleep after interrupt