MSP430USBDevelopersPackage_5_20_06_02
|
Functions | |
uint8_t | USB_init (void) |
uint8_t | USB_setup (uint8_t connectEnable, uint8_t eventsEnable) |
uint8_t | USB_enable () |
uint8_t | USB_disable (void) |
uint8_t | USB_setEnabledEvents (uint16_t events) |
uint16_t | USB_getEnabledEvents () |
uint8_t | USB_connect () |
uint8_t | USB_disconnect () |
uint8_t | USB_reset () |
uint8_t | USB_suspend (void) |
uint8_t | USB_resume (void) |
uint8_t | USB_forceRemoteWakeup () |
uint8_t | USB_getConnectionInformation () |
uint8_t | USB_getConnectionState () |
uint8_t | USBHID_sendDataAndWaitTillDone (uint8_t *dataBuf, uint16_t size, uint8_t intfNum, uint32_t ulTimeout) |
uint8_t | USBHID_sendDataInBackground (uint8_t *dataBuf, uint16_t size, uint8_t intfNum, uint32_t ulTimeout) |
uint16_t | USBHID_receiveDataInBuffer (uint8_t *, uint16_t, uint8_t) |
uint8_t | USBCDC_sendDataAndWaitTillDone (uint8_t *dataBuf, uint16_t size, uint8_t intfNum, uint32_t ulTimeout) |
uint8_t | USBCDC_sendDataInBackground (uint8_t *dataBuf, uint16_t size, uint8_t intfNum, uint32_t ulTimeout) |
uint16_t | USBCDC_receiveDataInBuffer (uint8_t *, uint16_t, uint8_t) |
uint8_t 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().
uint8_t 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_getConnectionState() begins returning ST_USB_DISCONNECTED, this function should be called (following a call to USB_disconnect()), in order to avoid unnecessary current draw.
uint8_t 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.
uint8_t 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.
uint8_t 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 USB_GENERAL_ERROR, it means that the host did not grant the device the ability to perform a remote wakeup, when it enumerated the device.
uint8_t USB_getConnectionInformation | ( | ) |
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, USB_VBUS_PRESENT + USB_SUSPENDED.
uint8_t USB_getConnectionState | ( | ) |
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".
uint16_t 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().
uint8_t 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.
uint8_t 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().
uint8_t USB_resume | ( | void | ) |
Resume USB.
uint8_t USB_setEnabledEvents | ( | uint16_t | events | ) |
Enables/Disables the Various USB Events.
events | is the mask for what is to be enabled/disabled.
|
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 USB_ALL_USB_EVENTS 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.
uint8_t USB_setup | ( | uint8_t | connectEnable, |
uint8_t | 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.
connectEnable | If TRUE, Connect to host if VBUS is present by pulling the D+ signal high using the PUR pin. |
eventsEnable | If TRUE, all USB events handlers are enabled |
uint8_t USB_suspend | ( | void | ) |
Suspend USB.
uint16_t USBCDC_receiveDataInBuffer | ( | uint8_t * | , |
uint16_t | , | ||
uint8_t | |||
) |
Opens a Receive Operation
*dataBuf | is the address of the data buffer. |
size | is the size of the data. |
intfnum | intfNum is which CDC interface is being used. |
Opens a brief receive operation for any data that has already been received into the USB buffer over interface intfNum. This call only retrieves data that is already waiting in the USB buffer – that is, data that has already been received by the MCU. It assumes a previous, open receive operation (began by a direct call to USBxxx_receiveData()) is NOT underway on this interface; and no receive operation remains open after this call returns. It doesn't check for kUSBxxx_busNotAvailable, because it doesn't matter if it's not. The data in the USB buffer is copied into dataBuf, and the function returns the number of bytes received.
size is the maximum that is allowed to be received before exiting; i.e., it is the size allotted to dataBuf. If size bytes are received, the function ends, returning size. In this case, it???s possible that more bytes are still in the USB buffer; it might be a good idea to open another receive operation to retrieve them. For this reason, operation is simplified by using large size values, since it helps ensure all the data is retrieved at one time.
This function is usually called when a USBCDC_handleDataReceived() event flags the application that data has been received into the USB buffer.
uint8_t USBCDC_sendDataAndWaitTillDone | ( | uint8_t * | dataBuf, |
uint16_t | size, | ||
uint8_t | intfNum, | ||
uint32_t | ulTimeout | ||
) |
Completely Sends the Data in dataBuf
*dataBuf | is the address of the data buffer. |
size | is the size of the data. |
intfnum | intfNum is which interface is being used. |
ulTimeout | is the (32-bit) number of polls to USBCDC_getInterfaceStatus(). |
Sends the data in dataBuf, of size size, using the post-call polling method. It does so over interface intfNum. The function doesn???t return until the send has completed. Because of this, the user buffer can be edited immediately after the function returns, without consequence. The function assumes that size is non-zero. It assumes no previous send operation is underway.
The 32-bit number ulTimeout selects how many times USBCDC_getInterfaceStatus() will be polled while waiting for the operation to complete. If the value is zero, then no timeout is employed; it will wait indefinitely. When choosing a number, it is advised to consider MCLK speed, as a faster CPU will cycle through the calls more quickly. The function provides the simplest coding, at the expense of wasted cycles and potentially allowing MCU execution to become "locked" to the host, a disadvantage if the host (or bus) is slow.
The function also checks all valid return codes, and returns non-zero if an error occurred. In many applications, the return value can simply be evaluated as zero or non-zero, where nonzero means the call failed for reasons of host or bus non-availability. Therefore, it may desirable for the application to break from execution. Other applications may wish to handle return values 1 and 2 in different ways.
It???s recommended not to call this function from within an event handler. This is because if an interface currently has an open send operation, the operation will never complete during the event handler; rather, only after the ISR that spawned the event returns. Thus the USBCDC_getInterfaceStatus() polling would loop indefinitely (or timeout). It???s better to set a flag from within the event handler, and use this flag to trigger the calling of this function from within main().
uint8_t USBCDC_sendDataInBackground | ( | uint8_t * | dataBuf, |
uint16_t | size, | ||
uint8_t | intfNum, | ||
uint32_t | ulTimeout | ||
) |
Completely Sends the Data in dataBuf
*dataBuf | is the address of the data buffer. |
size | is the size of the data. |
intfnum | intfNum is which interface is being used. |
ulTimeout | is the (32-bit) number of polls to USBCDC_getInterfaceStatus(). |
Sends the data in dataBuf, of size size, using the pre-call polling method. It does so over interface intfNum. The send operation may still be active after the function returns, and dataBuf should not be edited until it can be verified that the operation has completed. The function assumes that size is non-zero. This call assumes a previous send operation might be underway.
The 32-bit number ulTimeout selects how many times USBCDC_getInterfaceStatus() will be polled while waiting for the previous operation to complete. If the value is zero, then no timeout is employed; it will wait indefinitely. When choosing a number, it is advised to consider MCLK speed, as a faster CPU will cycle through the calls more quickly. The function provides simple coding while also taking advantage of the efficiencies of background processing. If a previous send operation is underway, this function does waste cycles polling, like xxxsendDataWaitTilDone(); however it's less likely to do so since much of the sending presumably took place in the background since the last call to xxxsendDataInBackground().
The function also checks all valid return codes, and returns non-zero if an error occurred. In many applications, the return value can simply be evaluated as zero or non-zero, where nonzero means the call failed for reasons of host or bus non-availability. Therefore, it may desirable for the application to break from execution. Other applications may wish to handle return values 1 and 2 in different ways.
It???s recommended not to call this function from within an event handler. This is because if an interface currently has an open send operation, the operation will never complete during the event handler; rather, only after the ISR that spawned the event returns. Thus the USBCDC_getInterfaceStatus() polling would loop indefinitely (or timeout). It???s better to set a flag from within the event handler, and use this flag to trigger the calling of this function from within main().
uint16_t USBHID_receiveDataInBuffer | ( | uint8_t * | , |
uint16_t | , | ||
uint8_t | |||
) |
Opens a Receive Operation
*dataBuf | is the address of the data buffer. |
size | is the size of the data. |
intfnum | intfNum is which HID interface is being used. |
Opens a brief receive operation for any data that has already been received into the USB buffer over interface intfNum. This call only retrieves data that is already waiting in the USB buffer – that is, data that has already been received by the MCU. It assumes a previous, open receive operation (began by a direct call to USBxxx_receiveData()) is NOT underway on this interface; and no receive operation remains open after this call returns. It doesn't check for kUSBxxx_busNotAvailable, because it doesn't matter if it's not. The data in the USB buffer is copied into dataBuf, and the function returns the number of bytes received.
size is the maximum that is allowed to be received before exiting; i.e., it is the size allotted to dataBuf. If size bytes are received, the function ends, returning size. In this case, it???s possible that more bytes are still in the USB buffer; it might be a good idea to open another receive operation to retrieve them. For this reason, operation is simplified by using large size values, since it helps ensure all the data is retrieved at one time.
This function is usually called when a USBHID_handleDataReceived() event flags the application that data has been received into the USB buffer.
uint8_t USBHID_sendDataAndWaitTillDone | ( | uint8_t * | dataBuf, |
uint16_t | size, | ||
uint8_t | intfNum, | ||
uint32_t | ulTimeout | ||
) |
Completely Sends the Data in dataBuf
*dataBuf | is the address of the data buffer. |
size | is the size of the data. |
intfnum | intfNum is which HID interface is being used. |
ulTimeout | is the (32-bit) number of polls to USBHID_getInterfaceStatus(). |
Sends the data in dataBuf, of size size, using the post-call polling method. It does so over interface intfNum. The function doesn???t return until the send has completed. Because of this, the user buffer can be edited immediately after the function returns, without consequence. The function assumes that size is non-zero. It assumes no previous send operation is underway.
The 32-bit number ulTimeout selects how many times USBHID_getInterfaceStatus() will be polled while waiting for the operation to complete. If the value is zero, then no timeout is employed; it will wait indefinitely. When choosing a number, it is advised to consider MCLK speed, as a faster CPU will cycle through the calls more quickly. The function provides the simplest coding, at the expense of wasted cycles and potentially allowing MCU execution to become "locked" to the host, a disadvantage if the host (or bus) is slow.
The function also checks all valid return codes, and returns non-zero if an error occurred. In many applications, the return value can simply be evaluated as zero or non-zero, where nonzero means the call failed for reasons of host or bus non-availability. Therefore, it may desirable for the application to break from execution. Other applications may wish to handle return values 1 and 2 in different ways.
It's recommended not to call this function from within an event handler. This is because if an interface currently has an open send operation, the operation will never complete during the event handler; rather, only after the ISR that spawned the event returns. Thus the USBHID_getInterfaceStatus() polling would loop indefinitely (or timeout). It???s better to set a flag from within the event handler, and use this flag to trigger the calling of this function from within main().
uint8_t USBHID_sendDataInBackground | ( | uint8_t * | dataBuf, |
uint16_t | size, | ||
uint8_t | intfNum, | ||
uint32_t | ulTimeout | ||
) |
Completely Sends the Data in dataBuf
*dataBuf | is the address of the data buffer. |
size | is the size of the data. |
intfnum | intfNum is which HID interface is being used. |
ulTimeout | is the (32-bit) number of polls to USBHID_getInterfaceStatus(). |
Sends the data in dataBuf, of size size, using the pre-call polling method. It does so over interface intfNum. The send operation may still be active after the function returns, and dataBuf should not be edited until it can be verified that the operation has completed. The function assumes that size is non-zero. This call assumes a previous send operation might be underway.
The 32-bit number ulTimeout selects how many times USBHID_getInterfaceStatus() will be polled while waiting for the previous operation to complete. If the value is zero, then no timeout is employed; it will wait indefinitely. When choosing a number, it is advised to consider MCLK speed, as a faster CPU will cycle through the calls more quickly. The function provides simple coding while also taking advantage of the efficiencies of background processing. If a previous send operation is underway, this function does waste cycles polling, like xxxsendDataWaitTilDone(); however it's less likely to do so since much of the sending presumably took place in the background since the last call to xxxsendDataInBackground().
The function also checks all valid return codes, and returns non-zero if an error occurred. In many applications, the return value can simply be evaluated as zero or non-zero, where nonzero means the call failed for reasons of host or bus non-availability. Therefore, it may desirable for the application to break from execution. Other applications may wish to handle return values 1 and 2 in different ways.
It???s recommended not to call this function from within an event handler. This is because if an interface currently has an open send operation, the operation will never complete during the event handler; rather, only after the ISR that spawned the event returns. Thus the USBHID_getInterfaceStatus() polling would loop indefinitely (or timeout). It???s better to set a flag from within the event handler, and use this flag to trigger the calling of this function from within main().