MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

Transcription

1 September 2008 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 MSP430 Contents 1 Introduction Operation System Stack Organization Source File Organization Use of MCU Resources Configuration of Endpoints Descriptors Configurations Serial Numbers Configuration Constants in descriptors.c Data Transmission/Reception Interface Power Management Clock System Version Host Considerations Microsoft Windows Apple MacOS Linux API Function Calls MSP430 USB Module Management BYTE USB_init() BYTE USB_enable(WORD freq) BYTE USB_disable(void) (not implemented in v0.7) BYTE USB_setEnabledEvents(BYTE events) BYTE USB_getEnabledEvents(void) USB Connection Management BYTE USB_reset() BYTE USB_connect() BYTE USB_disconnect(void) BYTE USB_forceRemoteWakeup(void) BYTE USB_connectionStatus() CDC Management and Data Handling BYTE USBCDC_sendData(BYTE * data, WORD size, BYTE portnum) BYTE USBCDC_receiveData(BYTE * data, WORD size, BYTE portnum) BYTE USBCDC_abortSend(WORD* size, BYTE portnum) BYTE USBCDC_abortReceive(WORD* size, BYTE portnum) (not implemented in v0.7) BYTE USBCDC_rejectData()

2 3.3.6 BYTE USBCDC_portStatus(BYTE portnum, WORD* bytessent, WORD* bytesreceived) (not implemented in v0.7) BYTE USBCDC_getPortSettings(LONG rate, BYTE format, BYTE parity, BYTE databits, BYTE portnum) (not implemented in v0.7) Event-Handling void USB_handleClockEvent(void) void USB_handleVbusOnEvent(void) void USB_handleVbusOffEvent(void) void USB_handleResetEvent(void) void USB_handleSuspendEvent(void) void USB_handleResumeEvent(void) void USB_handleDataReceived(BYTE portnum) void USB_handleSendCompleted(BYTE portnum) void USB_handleReceiveCompleted(BYTE portnum) Operation Examples Initialization Handling a VBUS-On Event Sending Data Receiving Data Configuration Constants References...28 Figures Figure 1. USB Software Stack with CDC API...4 Figure 2. USB Initialization...25 Figure 3. handlevbusonevent()...25 Tables Table 1. Files in the API Stack...5 Table 2. Endpoint Usage...6 Table 3. USB Module Management Call Summary...10 Table 4. for USB_init()...11 Table 5. for USB_enable()...11 Table 6. for USB_disable()...11 Table 7. for USB_setEnabledEvents()...12 Table 8. for USB_getEnabledEvents()...13 Table 9. USB Connection Management Call Summary...13 Table 10. for USB_reset ()...13 Table 11. for USB_connect()...14 Table 12. for USB_disconnect()...14 Table 13. for USB_forceRemoteWakeup()...15 Table 14. for USB_connectionStatus()...15 Table 15. CDC Management and Data Handling Call Summary...16 Table 16. for USBCDC_sendData()...17 Table 17. for USBCDC_receiveData()...18 Table 18. for USBCDC_abortSend()...18 Table 19. for USBCDC_abortReceive()...19 Table 20. for USBCDC_rejectData() MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

3 Table 21. for USBCDC_portStatus()...20 Table 22. for USBCDC_getPortSettings()...21 Table 23. Event Handler Summary...22 Table 24. Configuration Constants Introduction The USB CDC API (USB Communications Device Class Application Programming Interface) for the MSP430 is a turnkey API that makes it easy to implement a simple data connection over USB between an MSP430-based device and a USB host. It abstracts the user from the USB protocol, making the connection as simple as using a UART while still providing a sufficient amount of configuration. To the USB host, the connection appears as a virtual COM port, which is a very simple and commonly-used interface. To the MSP430 s software, it appears as a simple data port that is accessible with simple API calls, such as open/close the connection, send/receive data, etc. Up to three data connections (i.e., three COM ports on the host associated with three conceptual ports within the MSP430) can be established simultaneously using this API. (Note: v0.7 only supports a single port connection.) All usage of the API should be supportable via the provided calls, and the user should not need to modify the API source. However, the source is made available to the user to assist in understanding the entire system, if needed. Note: v0.7 of this API is a preliminary version that has been readied for use with pre-production samples of the MSP430TC0701 device. This specification reflects what v1.0 is intended to become. Some features defined in this user s guide are not yet implemented, and these are marked with notes in italics. While it is intended to keep the v1.0 definition similar to what is defined here, the existing function calls are subject to change and should be used for evaluation purposes only. No guarantees are made for future compatibility. 2 Operation 2.1 System The purpose of this API is the establishment of a COM port on the USB host, through which an application on the host can communicate with an MSP430 over USB. On the MSP430 side, each PC COM port is associated with a virtual port, through which data is transceived with the host. (The term COM port is specific to the Windows group of operating systems, but the MacOS, Linux, and other PC-oriented operating systems provide similar mechanisms. The term COM port will be used throughout this document to refer to all of them.) MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 3

4 The COM port software mechanism is a popular means of communicating with a peripheral from a PC, due to its simplicity. It was originally designed for communication over the RS232 port, but it has now grown beyond these hardware limitations. Often today it is used in the form of a virtual COM port operating over USB or Bluetooth, interfaces which by now have mostly replaced RS232 on the PC back panel. Historically, COM ports were used in telecom applications, including modems and early networking applications. Although these applications for COM ports have all but been replaced by other uses, this telecom influence exists to this day. For example, programs whose primary function is to interface with COM ports are still referred to as terminal applications, a term derived from these early roots. One means of establishing a virtual COM port interface over USB is with the Communications Device Class (CDC) protocol, which was established by the USB Implementers Forum. The major OSes have already included support for this protocol as part of their basic installations; and so for most applications, the end user need not install custom kernel drivers. This leads to greater system stability, less hassle for the end user, and considerably less hassle for the OEM, in terms of development cost and end user support. The scope of the CDC spec is much wider than virtual COM ports, supporting a wide variety of communications equipment. As a result, this API supports only a subset of the CDC spec. Specifically, it supports the Abstract Communication Model (ACM) of the PSTN subclass. The ACM provides for a control mechanism using common V.250 AT commands. This is sufficient to establish a fully-functional virtual COM port interface. Up to three data connections can be established using this current version of this API. Each connection represents a data link between a COM port on the PC, and conceptual ports within the API. (Note: v0.7 only supports a single port.) Simple calls are available to transceive data with the USB host, at a level of complexitiy similar to that of a basic UART. 2.2 Stack Organization A code stack using this API is shown in Fig. 1. Application API Event Handlers CDC API USB API User code User-customized event handling Modification unnecessary MSP430 header file Figure 1. USB Software Stack with CDC API 4 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

5 The USB functionality is almost fully contained within the API, allowing the user to focus on data handling rather than protocol. Some calls are common to any USB interface, such as initialization, connecting to the USB, etc. These are located within the USB API and made available to the application. Other calls are specific to the CDC; the CDC interfaces with the USB API to actualize the CDC protocol. The USB API is shared among all USB device class API stacks distributed by TI for the MSP430, easing the development of composite devices with multiple device class APIs. Interrupt handling (that is, the USB interrupt service routine) is performed within the API, as opposed to user-defined application space. However, the API provides to the application a means of responding to interrupts through events. These are occurrences for which the developer can add custom handling to the handling already implemented by the API. Handling of events is implemented through placeholder functions defined in application space, but called from within the USB ISR. These functions can be customized to the application. For example, if a power event has been detected that has disrupted USB operation, the application may choose to investigate the problem or alert the end user of a low battery. See Sec. 4 for more information about event handler functions. 2.3 Source File Organization Source and header files that comprise the API stack are shown in Table 1. Table 1. Files in the API Stack User- Modify? Filename Applicationspecific Yes main.c usb_eventhandling.c User application. Event-handling placeholder functions. descriptors.c File containing functions that reply to the host s GetDescriptor requests. A default descriptor set is provided, which can be customized directly or with the MSP430 USB Descriptor Tool. This file also contains the configuration constants, as described in Sec. 6 CDC-related functions. All non-cdc and non-hid, USB-level functions; descriptor handling; API-defined calls made from ISR vector. API stack No usbcdc.c usb.c usbisr.c USB interrupt service routine handler and related functions. MSP430 header file No I.e., MSP430xx55x2.h Standard header file for the MSP430 device derivative being used. This is included in the software development environment, outside this API. 2.4 Use of MCU Resources Within the API, two resources are used without restriction -- the USB module (with its associated pins), and two DMA channels. (Note: v0.7 does not use the DMA for data transfers.) Generally speaking, the application should avoid direct writing to either the USB module or the DMA modules control of the selected channels. MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 5

6 The pins associated with the USB module can be used as special I/O pins when not used for USB. The application has permission to manipulate these pins directly only when the USB module has been disabled using the USB_disable() call. Once the USB module is enabled using USB_enable(), the API has the right to control these pins. Two DMA channels must be assigned to the API, one for transmit and one for receive. The channels are assigned using the configuration constants USB_DMA_TX and USB_DMA_RX The API v0.7 uses approximately 3.7K bytes of code memory and 500 bytes of data memory. 2.5 Configuration of Endpoints The CDC specification provides for a management element, and optionally a notification element that the device can use to alert the host. The former is predefined to use control endpoint 0, while the latter can use an interrupt or bulk endpoint. The PSTN subclass of the CDC, which defines the Abstract Control Model implemented by this API, provides for an additional pair of pipes to exchange data with the host. The API implements this structure as shown in Table 2. Table 2. Endpoint Usage Endpoint Transfer Type Purpose Control endpoint 0 (input/output) Control Management element Input endpoint 2 (IN2) Interrupt Notification element Input/output endpoint 3 (IN3/OUT3) Bulk For port #1 Input/output endpoint _ (IN_/OUT_) Bulk For port #2 (not supported in v0.7) Input/output endpoint _ (IN_/OUT_) Bulk For port #3 (not supported in v0.7) 2.6 Descriptors The USB descriptors reported by the CDC API to the USB host reflect the requirements of the CDC specification as implemented by the API. The code that does this is contained in the file descriptors.c. In their unmodified form as distributed by TI, the API s descriptor handlers are sufficient for application development. They report the device using TI s vendor ID, a product ID specific to this API, and TI-specific vendor/product strings. For production purposes, however, they should be customized. In almost all cases, at least the device descriptor and string descriptors will need to be customized. TI has provided the MSP430 USB Descriptor Tool as an open-source solution to help with this customization. The tool quickly modifies descriptors.c using a graphical interface, saving time and greatly reducing the chance for unnecessary errors. (Note: As of September 2008, the MSP430 USB Descriptor Tool has not yet been developed. Modifications of the descriptors is not necessary for evaluation of this API, only for release of a product.) 6 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

7 2.6.1 Configurations The API s default descriptor set provides for a single USB configuration. If more than one configuration is desired, it is up to the user to create it. The provided configuration, including the interface and endpoint descriptors beneath it in the descriptor tree, are specific to the CDC implementation established by this API. With the exception of the fields that report power consumption, there should be no need to change them. The default configuration descriptor provides string descriptors for the configuration/interface descriptors. Although the configuration descriptor should not change, these string descriptors should be customized prior to release of a USB product Serial Numbers The iserialnumber field in the device descriptor determines whether the USB device intends to report a unique serial number to the host. If null, this indicates to the host that it will not report one. If it contains an index to a valid string descriptor, this string descriptor s contents are considered to be the serial number. The serial number cannot be determined at compile time, because it is specific to an individual MSP430 device and derived from the device ID, read by the API at run-time. The default descriptor structures in descriptors.c include a string descriptor for the serial number, equipped with a dummy eight-bit value. This dummy serial number descriptor is indexed by iserialnumber, which means that the host will expect the descriptor to be reported at this index. When the host issues a GET_DESCRIPTORS request, the API uses this descriptor structure and determines whether the iserialnumber field is non-null; if so, it fetches the die ID for the individual MSP430 device and substitutes it into this dummy descriptor, prior to reporting it to the host. As a result, the default behavior is to report a serial number specific to the individual MSP430 device. If a serial number is not desired, iserialnumber needs to be set to null. The API will then exclude the serial number string descriptor. (Note: v0.7 of the API does not reflect this behavior it merely sends what is specified in descriptors.c.) Configuration Constants in descriptors.c Some elements of the API are controlled through configuration constants. These are compiletime controls that do not change during operation. (See Sec. 6) Some of the descriptor information is implemented using configuration constants, which is intended to make it easier to make changes to the descriptors, and also makes the information available to the API code, should it be necessary. (Note: v0.7 of the API does not implement the configuration constants.) 2.7 Data Transmission/Reception Interface (Note: While the data transmission/reception scheme in v1.0 will bear many similarities to the one in v0.7, there will be differences. This section discusses what is implemented in v0.7 and what is planned for v1.0.) MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 7

8 The API provides a simple scheme of transmitting and receiving data with the USB host, using commands such as send data and receive data. In so doing, it abstracts the user from the USB and CDC protocols, handling these functions automatically. From the application s perspective, communication with the USB host occurs via a port within the API, which is associated with a particular COM port on the USB host. (While, v0.7 supports only one COM port, v1.0 will support more, according to the constant USB_MAX_PORTCOUNT in descriptors.c.) An important factor in the tranceiving of USB data is the maximum packet size. v0.7 fixes this at 64 bytes, while v1.0 will allow this to be adjusted with the configuration constant USB_MAX_PACKET_SIZE. If data sizes larger than the packet size are to be sent, then after the API has finished loading USB_MAX_PACKET_SIZE bytes into the buffers, the application must wait until this data has been sent over the bus before loading data again. Similarly, if data sizes larger than the packet size are to be received, then after this much data has been removed from the buffers, the application must wait until more has been received over the bus. The API ensures that the application has control during these wait periods so that the USB operation does not monopolize the CPU s time. Data can be sent through a port with the function USBCDC_SendData() and received with the function USBCDC_ReceiveData(). Each of these functions exchanges the data with a location in memory, the address and size of which is passed into the function call by the application. If the size value passed to USBCDC_SendData() is less than 64 bytes, the function writes the data to the USB buffers and initiates the transfer, and then the function returns. If the size value passed to USBCDC_SendData() is greater than 64 bytes, the function sends the first 64 bytes, flags an interrupt to be generated when the buffer is once again empty, and the function returns. At this point, a send operation is said to be underway. When the first 64 bytes have been transmitted and the buffer is empty, an interrupt is generated and the next 64 bytes are sent. This process repeats until all the data has been sent, at which point the send operation is said to be completed. In this way, using send operations, data sizes larger than 64 bytes can be sent by the application using a single function call. While the operation is underway, no new operations for that port can be started. If one is attempted, USBCDC_SendData() returns the value kusbcdc_portbusyerror. A send operation can be aborted using USBCDC_abortSend(). In contrast, the USBCDC_ReceiveData() function is only capable of receiving up to 64 bytes. When the function is called, the received data is copied out of the USB buffers and the function returns. As more data is received over the bus, new calls to USBCDC_ReceiveData() must be made. v1.0 will provide more control for automatic receive operations greater than 64 bytes, similar to that currently provided for send operations.. A function call USBCDC_portStatus() will be available in v1.0 to indicate whether an operation is still underway. When a send operation completes, there is a pair of events, SendCompleteEvent and ReceiveCompleteEvent, which can generate a user-handlable event, when enabled. 8 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

9 If a receive operation is not underway for a given port, and data arrives that is designated for that port, it generates a DataReceivedEvent, and the transfer of any data over USB either send/receive, and for any port, or even responding to any kind of USB requests from the host -- is halted until either a receive operation is begun (at which point the data is immediately transferred to memory) or the data is rejected with USBCDC_rejectData(). Until one of these actions is taken, the packet that delivered the data will remain in the USB buffers; all attempts by the host to send a packet to this device will be NAK ed, and although send operations can be initiated by the MSP430 application, no progress will be made in transferring data to the host. A port may have one send operation and one receive operation but not more than one of either -- simultaneously. 2.8 Power Management The MSP430 s USB module has an integrated LDO regulator that reduces the 5V VBUS power supply from the USB to 3.3V. The MSP430 can then be powered from the USB. Further, the output of this LDO is such that it may be possible to supply the entire system outside the MSP430. The MSP430 has the ability to detect when VBUS has been made available to it and automatically enable/disable the LDO accordingly, generating an interrupt to let software know of the change. This makes it easy to prevent unnecessary drain on the system s power supply, which is important in battery-powered applications. The current version of the API supports the automatic enabling/disabling of the 3.3V LDO. 2.9 Clock System MSP430 devices supporting USB include a PLL that generates a USB clock from a high-speed crystal on the XT1/XT2 oscillator. A wide range of crystal frequencies is supported. The API must be told at what frequency the crystal oscillator is operating, so that it can configure the dividers in the PLL. The current version of the API supports the configuration of frequencies by having the application pass a constant that reflects the frequency of the crystal. 43 discrete crystal frequencies between MHz are supported, using values in the MSP430 header file. (Note: v0.7 of the API, designed specifically for the MSP430TC0701, uses XT1 as the source clock for the PLL. This has been done to work around a TC0701 errata item, and the hardware distributed with the TC0701 has a high-frequency crystal on XT1 instead of XT2. See the TC0701 errata document.) 2.10 Version It is possible to identify the version of the API when the device is plugged into a PC, using the OS. In Windows, this is done by opening the Device Manager and selecting the virtual COM port within the Ports section. (The Device Manager is Windows mechanism to manage peripherals on the system, and can be opened by right-clicking on My Computer and pressing the Device Manager button in the Hardware tab.) MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 9

10 2.11 Host Considerations Microsoft Windows Windows responds to the descriptors reported by this API by establishing a COM port link, similar to what it does with legacy RS232 hardware serial ports. The most basic Windows application that can utilize a COM port is Hyperterminal, which is a part of any Windows installation. An MSP430 board loaded with this API, attached to a Windows-equipped USB host, will allow communication with Hyperterminal, once the proper COM port has been chosen within Hyperterminal. The CDC class is supported by Windows XP and Vista Apple MacOS Linux 3 API Function Calls 3.1 MSP430 USB Module Management These calls configure and manage the MSP430 s USB module. They are shared among all USB APIs distributed by TI for the MSP430, and they are all defined within the usb.c source file. Table 3. USB Module Management Call Summary Function BYTE USB_init() BYTE USB_enable(WORD freq) BYTE USB_disable() BYTE USB_setEnabledEvents(WORD events) BYTE USB_getEnabledEvents() Initializes the USB hardware interface by configuring interrupts, power, and clocks, but does not activate the PLL or transceiver. Activates the USB module, PLL, and transceiver. Disable USB module, PLL, and transceiver. (not supported in v0.7) Enables/disables various USB events Returns the status of USB event enabling BYTE USB_init() Initializes the USB module by configuring power and clocks, and secures the assocated pins for USB rather than general I/O usage. This should be called prior to any other API functions. 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. As such, power consumption does not increase when this function is executed. 10 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

11 Table 4. for USB_init() returns kusb_succeed result = USB_init(); if (USB_connectionStatus() & kusbvbuspresent) result = USB_enable(USBPLL_SETCLK_1_5); BYTE USB_enable(WORD freq) Enables the USB module, which includes activating the PLL and setting the USB_EN bit. Power consumption increases as a result of this operation. Table 5. for USB_enable() word freq returns The frequency of the crystal sourcing the PLL. This value should be taken from the MSP430 header file, in the section specifying values to be assigned to the USBPLLDIVB register. kusb_succeed result = USB_enable(USBPLL_SETCLK_1_5); BYTE USB_disable(void) (not implemented in v0.7) Disables the USB module and PLL. If the USB is not enabled when this call is made, no error is returned the call simply exits with success. Table 6. for USB_disable() Returns kusb_succeed MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 11

12 result = USB_disable(); BYTE USB_setEnabledEvents(BYTE events) Enables/disables various USB events. The events byte takes effect as-is; all 1 values are enabled, and all 0 values are 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. Table 7. for USB_setEnabledEvents() word events Returns kusb_clockfaultevent kusb_vbusonevent kusb_vbusoffevent kusb_usbresetevent kusb_usbsuspendevent kusb_usbresumeevent kusb_datareceivedevent kusb_sendcompletedevent kusb_receivecompletedevent kusb_succeed result = USB_SetEnabledEvents(kUSB_VbusOnEvent kusb_sendcompletedevent); BYTE USB_getEnabledEvents(void) 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. 12 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

13 Table 8. for USB_getEnabledEvents() Returns kusb_clockfaultevent kusb_vbusonevent kusb_vbusoffevent kusb_usbresetevent kusb_usbsuspendevent kusb_usbresumeevent result = USB_GetEnabledEvents(); 3.2 USB Connection Management These calls pertain to the USB connection with the host. They are shared among all USB APIs distributed by TI for the MSP430 and are defined within the usb.c source file. Table 9. USB Connection Management Call Summary Function BYTE USB_reset() BYTE USB_connect() BYTE USB_disconnect() BYTE USB_forceRemoteWakeup() BYTE USB_connectionStatus() Resets the USB module and the internal state of the API. Instructs USB module to make itself available to the PC for connection, by pulling the PUR pin high. Forces a disconnect from the PC by pulling the PUR pin low Forces a remote wakeup of the USB host Returns the status of the USB connection BYTE USB_reset() Resets the USB module and also the internal state of the API. The interrupt register is cleared to make sure no interrupts are pending. All open send/receive operations are aborted (their corresponding data locations are left intact). Table 10. for USB_reset () returns kusb_succeed MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 13

14 result = USB_reset(); BYTE USB_connect() Instructs the USB module to make itself available to the PC for connection, by pulling the D+ signal high using the PUR pin. If this function is called while the USB module is not enabled or while VBUS is not present, the PUR pin is still pulled high, and the call exits with success. Table 11. for USB_connect() Returns kusb_succeed if(usb_connectionstatus() & kusbvbuspresent) { result = USB_enable(); result = USB_connect(); } BYTE USB_disconnect(void) 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 clearing the bit that pulls PUR high. Table 12. for USB_disconnect() Returns kusb_succeed 14 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

15 result = USB_disconnect(); BYTE USB_forceRemoteWakeup(void) Forces a remote wakeup of the USB host. The user must ensure that the configuration constant USB_SUPPORT_REMOTE_WAKEUP reflects that this capability exists, prior to calling this function. (v0.7 does not support configuration constants. Default descriptors report to the host that remote wakeup is supported, so this function may be called.) Table 13. for USB_forceRemoteWakeup() Returns kusb_succeed kusb_notsuspended #pragma vector=port1_vector interrupt void Port1_ISR (void) { // ISR entered because of an edge event on P1 P1IFG &= ~0x10; // IFG Cleared } if(usb_connectionstatus() & kusbsuspended) result = USB_forceRemoteWakeup(); BYTE USB_connectionStatus() Returns the status of the USB connection. Generally, the USB connection is either active or in suspend mode. Table 14. for USB_connectionStatus() Returns kusb_vbuspresent kusb_suspended kusb_connectnovbus (not implemented in v0.7) kusb_enumerated MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 15

16 if(usb_connectionstatus() & kusbsuspended) result = USB_forceRemoteWakeup(); 3.3 CDC Management and Data Handling These calls are specific to the Communications Device Class. They are defined within the usbcdc.c source file. Table 15. CDC Management and Data Handling Call Summary Function BYTE USBCDC_sendData(const BYTE* data, WORD size, BYTE portnum, BYTE DMA_ch) (refer Note 1) BYTE USBCDC_receiveData(BYTE* data, WORD size, BYTE portnum, BYTE DMA_ch) (refer Note 1) BYTE USBCDC_abortsend(WORD* size, BYTE portnum) (refer Note 2) Sends data to the USB host Receives data from the USB host Aborts an active send operation BYTE USBCDC_abortsend(WORD* size, BYTE portnum) (refer Note 2) Aborts an active receive operation BYTE USBCDC_rejectData() USBCDC_getPortSettings(LONG rate, BYTE format, BYTE parity, BYTE databits, BYTE portnum) Rejects payload data residing in the USB buffer, for which a receive operation has not yet been initiated BYTE USBCDC_sendData(BYTE * data, WORD size, BYTE portnum) Sends data over port portnum, of size size and starting at address data. If size is larger than the USB buffer space, the function handles all packetization and buffer management. If size is less than or equal to the value specified by the configuration constant USB_MAX_PACKET_SIZE, then all the data is immediately transferred to the USB buffer, and when the function returns, the send operation will be complete. The function will return with the code kusbcdc_sendcomplete, and a call to USBCDC_portStatus() after the return will show the kusbcdc_waitingforsend bit to be cleared. 16 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

17 Overwrite this text with the Lit. Number If size is greater than USB_MAX_PACKET_SIZE, then USB_MAX_PACKET_SIZE bytes are sent and the function returns; the remaining data will be sent as buffer space becomes available. It does this by setting up a sequence in which USB interrupts indicate that the buffer is empty, and more data-in-waiting is sent by the ISR. When the function returns, it does so with the value kusbcdc_sendstarted, and the send operation is said to be still underway. During this time, a call to USBCDC_portStatus() will return with the kusbcdc_waitingforsend bit set. Once the operation is completed, this bit will be return cleared. The handlesendcompleted() event will also be generated when the event has completed. (Note: v0.7 fixes the packet size to 64 bytes, rather than deriving it from USB_MAX_PACKET_SIZE.) (Note: v0.7 does not support the USBCDC_portStatus() call.) If a send operation is already in progress for this port (USBCDC_portStatus() returns kusbcdc_waitingforsend), then this call will return kportbusyerror. A receive operation can occur simultaneous to a send operation for this port. If the device gets suspended by the USB host, any active send operations are dormant, and will resume if or when the device is resumed. If this behavior isn t desired, the application should respond to a suspend event by aborting any active send operations. Table 16. for USBCDC_sendData() byte* data word size byte portnum Returns An array of data to be sent Number of bytes to be sent, starting from address data. Which port the data should be transmitted over kusbcdc_sendstarted kusbcdc_sendcomplete kusbcdc_portbusyerror if(!(usb_connectionstatus() & kusbcdc_waitingforsend)) result = USBCDC_sendData(data,32,1,0x01); BYTE USBCDC_receiveData(BYTE * data, WORD size, BYTE portnum) Receives size bytes over port portnum, of size size, into memory starting at address data. If less than size bytes are currently in the receive buffer, then only the available data is copied to data. The number of bytes received is returned. If more than size bytes remain in the buffer, additional calls to USBCDC_receiveData() are required to retrieve them. size should not be greater than 64 bytes. MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 17

18 (In v1.0, this function will provide support for automatic reception of data sizes larger than USB_MAX_PACKET_SIZE, similar to what is provided for sending data.) Table 17. for USBCDC_receiveData() byte* data word size byte portnum Returns An array that will contains the data received. Number of bytes to be received Which port to receive from Number of bytes actually received BYTE USBCDC_abortSend(WORD* size, BYTE portnum) Aborts an active send operation on port portnum. Returns the number of bytes that were sent prior to the abort, in size. An application may choose to call this function in response to the device being suspended by the USB host. Otherwise, when the device is resumed, the operation will automatically commence sending its data. An application may also choose to call this function if the send operation doesn t happen as quickly as required by the application, perhaps due to an overloaded bus. Table 18. for USBCDC_abortSend() word* size byte portnum Returns Number of bytes that were sent prior to the abort action. The port for which the send should be aborted kusb_succeed 18 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

19 // abort a previously-established send operation If (USBCDC_portStatus(1, bytessent,bytesreceived) & kusbcdc_waitingforsend) Result = USBCDC_abortSend(size,1); BYTE USBCDC_abortReceive(WORD* size, BYTE portnum) (not implemented in v0.7) Aborts an active receive operation on port portnum. Returns the number of bytes that were received and transferred to the data location established for this receive operation. An application may choose to call this function if it decides it no longer wants to receive data from the USB host, if the host for whatever reason has stopped sending the expected data and wishes to recover by freeing the memory originally assigned for this data. Table 19. for USBCDC_abortReceive() word* size byte portnum Returns Number of bytes that were received and are waiting at the assigned address. The port for which the send should be aborted kusb_succeed // abort a previously-established receive operation If (USBCDC_portStatus(1,bytesSent,bytesReceived) & kusbcdc_waitingforreceive) Result = USBCDC_abortReceive(size,1); BYTE USBCDC_rejectData() This function rejects payload data that has been received from the host for a port that does not have an active receive operation underway. The USB buffers are effectively purged, and the data lost. This frees the USB path to resume communication. Table 20. for USBCDC_rejectData() Returns kusb_succeed MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 19

20 // Reject data residing in the USB buffer (and obstructing flow of incoming data // for other ports) BYTE USBCDC_portStatus(BYTE portnum, WORD* bytessent, WORD* bytesreceived) (not implemented in v0.7) Indicates the status of the port portnum. If a send operation is active for this port, the function also returns the number of bytes that have been transmitted to the host. If a receiver operation is active for this port, the function also returns the number of bytes that have been received from the host and are waiting at the assigned address. Table 21. byte portnum word* bytessent word* bytesreceived Returns for USBCDC_portStatus() Port number for which status is being retrieved. If a send operation is underway, the number of bytes that have been transferred to the host is returned in this location. If no send operation is underway, this returns zero. If a receive operation is underway, the number of bytes that have been transferred to the assigned memory location is returned in this location. If no receive operation is underway, this returns zero. kusbcdc_waitingforsend (indicates that a call to USBCDC_SendData() has been made, for which data transfer has not been completed) kusbcdc_waitingforreceive (indicates that a receive operation has been initiated, but not all data has yet been received) kusbcdc_datawaiting (indicates that data has been received from the host, waiting in the USB receive buffers) bytes_senda = USBCDC_sendData(dataA,8,1,0xFF); while(usbcdc_portstatus(1,bytessent,bytesreceived) & kusbcdc_waitingforsend); bytes_sendb = USBCDC_sendData(dataB,8,1,0xFF); BYTE USBCDC_getPortSettings(LONG rate, BYTE format, BYTE parity, BYTE databits, BYTE portnum) (not implemented in v0.7) Returns information received from the host regarding the virtual COM port to which this port is associated, including the baud rate, number of stop bits, parity type, and number of data bits. 20 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

21 Overwrite this text with the Lit. Number If the CPU is exchanging data directly with port portnum, this function most likely serves no purpose. However, if the software is written such that the port data is being transceived via one of the MSP430 s hardware UARTs, it might be desirable to configure that UART according to the information received by this function. Table 22. for USBCDC_getPortSettings() long rate byte format byte parity byte databits byte portnum Returns Baud rate. This is the parameter defined in the PSTN subclass spec as dwdterate. The number of stop bits: 0: 1 stop bit 1: 1.5 stop bits 2: 2 stop bits This is the parameter defined in the PSTN subclass spec as bcharformat. The type of parity to be used: 0: None 1: Odd 2: Even 3: Mark 4: Space This is the parameter defined in the PSTN subclass spec as bparitytype. The number of data bits to be used (5, 6, 7, 8, or 16). This is the parameter defined in the PSTN sublcass spec as bdatabits. The number of the port being queried. kusb_succeed kusb_datanotreceivedfromhost 4 Event-Handling The USB interrupt service routine (ISR) is contained within the API, and is not intended to be modified by the API user. Rather, it provides event handling within the application. Various events are defined, most of which are called directly from the ISR in response to various interrupt types. For each event type, a placeholder function is defined in USB_eventHandling.c. As distributed by TI, the API software has no code inside these function definitions they are empty functions. The user may write handlers for the various event types with which the function is associated. Generally speaking, parameters are not passed in or out of the event-handling functions. However, a few of the functions are specific to a particular port, and in these cases, the port number is passed into the function. MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 21

22 Event-handling calls are generally called from the ISR. As such, general interrupts are disabled prior to entering the handler function, and any precautions about good ISR coding apply to event handler functions as well. Notably, it is recommended that code be kept as short as possible to avoid delays in handling other interrupts. If more functionality is required, one option is to set a flag and let code outside the handler pick up the flag and handle the desired functionality. The event handler should never enable general interrupts, as unpredictable operation could result. Table 23. Event Handler Summary Event Handler functions Interrupt source Event VOID USB_handleClockEvent() USBVECINT_PLL_RANGE USB-PLL failed (out of range) VOID USB_handleVbusOnEvent() USBVECINT_PWR_VBUSOn Indicates that a valid voltage is now available on the VBUS pin VOID USB_handleVbusOffEvent() USBVECINT_PWR_VBUSOff Indicates that a valid voltage is no longer available on the VBUS pin VOID USB_handleResetEvent() USBVECINT_RSTR Indicates that the USB host has initiated a port reset VOID USB_handleSuspendEvent() USBVECINT_SUSR Indicates that the USB host has put this device into suspend mode VOID USB_handleResumeEvent() USBVECINT_RESR Indicates that the USB host has resumed this device from suspend mode VOID USB_handleDataReceived(BYTE portnum) VOID USB_handleSendCompleted(BYTE portnum) VOID USB_handleReceiveCompleted(BYTE portnum) Interrupt for the output endpoint associated with this port Interrupt for the input endpoint associated with this port Interrupt for the output endpoint associated with this port Indicates that data has been received for port portnum, for which no data receive operation is underway Indicates that a send operation on port portnum has just been completed Indicates that a send operation on port portnum has just been completed 4.1 void USB_handleClockEvent(void) If this function gets executed, it s a sign that the output of the USB PLL has failed. This event will occur even if no USB connection was established, if the event is enabled. This event may have occurred because the high-frequency crystal has failed. If this event occurs while the USB device is actively connected to the USB host, it probably means the host will soon consider this device non-operational, if it has not already done so by the time this call is executed. As a result, it will most likely suspend the device. After reestablishing the clock, it may be necessary to call USB_reset() to perform a logical disconnect/reconnect to the host, but removing and re-applying the pullup on the D+ signal. 22 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

23 4.1.1 void USB_handleVbusOnEvent(void) If this function gets executed, it indicates that a valid voltage has just been applied to the VBUS pin. This generally means that the device has been attached to an active USB host. The MSP430 hardware and API automatically enable the 3.3V LDO. No action is required by the application in order to enable USB operation; the USB module is enabled by the API prior to the event handler function being executed void USB_handleVbusOffEvent(void) If this function gets executed, it indicates that a valid voltage has just been removed from the VBUS pin. If power has been applied to the VUSB pin from another source, then the USB operation is unaffected. However, if the USB module was being powered from the 3.3V LDO, then the USB module has likely been powered down, and the connection has been lost. The API responds by disabling the USB module and PLL, and then it calls this event handling function, if enabled. Interrupt enable for VBUS on event is enabled to automatically detect valid VBUS voltage and to initialize the USB module appropriately. Software may wish to inform the user of the situation void USB_handleResetEvent(void) If this function gets executed, it indicates that the USB host has issued a reset of this USB device. The API handles this event automatically, and no action is required by the application to maintain USB operation. It is provided to the application for informational purposes void USB_handleSuspendEvent(void) If this function gets executed, it indicates that the USB host has chosen to suspend this USB device. When this occurs, it is important that this USB device not consume more than 500uA, per the USB 2.0 specification. The API automatically shuts down the PLL, a significant source of current draw, when a suspend event occurs. To replace it, it selects the XT?? (lowfrequency) clock source to drive the USB module. It then calls this event handler. The application developer should be aware of how much current the system is drawing from VBUS. Code should be written for this function that reduces current draw from VBUS to within the 500uA limit. MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 23

24 4.1.5 void USB_handleResumeEvent(void) If this function gets executed, it indicates that the USB host has chosen to resume this USB device from suspend mode. When this occurs, the device is no longer restricted to drawing under 500uA from VBUS. The MSP430 hardware and API automatically re-start the PLL, and active operation automatically resumes. Upon being resumed, the device is no longer restricted to drawing less than 500uA from VBUS. Therefore, the application may use this event handler to activate functions that were shut down during suspend void USB_handleDataReceived(BYTE portnum) This event indicates that data has been received for port portnum, but no data receive operation is underway. Effectively, the API doesn t know what to do with this data and is asking for instructions. Either a receive operation can be initiated, or the data can be rejected by calling USBCDC_rejectData(). Until one of these is performed, USB transactions cannot continue; any packets received from the USB host will be NAK ed, and while send operations can be initiated, they will not make any progress in transferring their data to the host. Therefore, it is critical that this event be handled immediately, ideally within this handler function. If this function is exited without one of these actions being taken, a call to USBCDC_portStatus() for this port (but not any other ports) will return kusbdatawaiting, which is another point at which the application could begin a receive operation or reject the data void USB_handleSendCompleted(BYTE portnum) This event indicates that a send operation on port port has just been completed void USB_handleReceiveCompleted(BYTE portnum) This event indicates that a receive operation on port port has just been completed. The data can be retrieved. It is located at the address assigned when the fetch was initiated. If the event occurs, it means that the full size that was requested by the fetch was indeed received. 5 Operation Examples The following are examples of common application scenarios. 24 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7

25 5.1 Initialization When the program starts, it should prepare the USB module for operation. These are settings that must be made prior to a USB connection. Program Start USB_init() USB_setEnabledEvents() Figure 2. USB Initialization Note that events are enabled after initialization. Prior to this, no event can be generated, including the detection of a VBUS-on event. Once this event is enabled (within USB_setEnabledEvents() ), a valid voltage on VBUS, if it exists, will immediately generate a VBUS-on event. 5.2 Handling a VBUS-On Event In most cases, the VBUS pin on the MSP430 is attached to the VBUS 5V supply on the USB cable, supplied from the host. When 5V is seen on this pin, it s a sign that a physical connection to the host has been initiated. In most cases, a device will then want to indicate its presence to the host so that it can be enumerated by it. Fig.?? shows a typical handler for a VBUS-on event. HandleVbusOnEvent handler USB_enable() USB_connect() Begin send/receive operations Figure 3. handlevbusonevent() Enabling the USB module activates the PLL, which consumes a signficant amount of current. It is best to wait with this operation until after VBUS has become available. The connect operation activates the pullup resistor, signalling to the host the presence of this device. MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7 25

26 5.3 Sending Data When the application decides it is ready to send data to a port, it should first prepare the data and then begin a send operation. If there is to be a continuous flow of data, in which the memory location is a buffer continually loaded from a data source, the USBCDC_sendData() call could be placed inside handlesendcompleteevent(). This way, when the initial send is finished, a second one will automatically begin. 5.4 Receiving Data An application can choose to initiate a receive operation in one of two ways. One is to begin a receive operation immediately after enabling the USB module; this way data is automatically transferred to the assigned memory location. In this case, it is also beneficial to begin a receive operation within handlereceivecompleteevent(), since the occurrence of this event means there is no longer an active receive operation for this port, and any further data received for this port will generate a handledatareceivedevent(). An alternative, simpler method is to begin all receive operations within the handledatareceivedevent() function, since this function will automatically be called whenever data is received from the host and no receive operation is underway. USB operation halts completely until this event is handled, so if this method is used, it s important to execute the handling quickly. 26 MSP430 USB Communications Device Class (CDC) API User s Guide, v0.7