USB Component  Version 5.1
MDK-Professional Middleware for USB Device and Host
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages
CDC: Communication Device Class Functions

Functions

void USBD_CDCn_ACM_Initialize (void)
 Called during USBD_Initialize to initialize the USB CDC class Device (Virtual COM Port)
 
void USBD_CDCn_ACM_Uninitialize (void)
 Called during USBD_Uninitialize to un-initialize the USB CDC class Device (Virtual COM Port)
 
void USBD_CDCn_ACM_Reset (void)
 Called during USB Bus reset to reset the USB CDC class Device (Virtual COM Port)
 
bool USBD_CDCn_ACM_SetLineCoding (CDC_LINE_CODING *line_coding)
 Change communication settings of USB CDC class Device (Virtual COM Port)
 
bool USBD_CDCn_ACM_GetLineCoding (CDC_LINE_CODING *line_coding)
 Retrieve communication settings of USB CDC class Device (Virtual COM Port)
 
bool USBD_CDCn_ACM_SetControlLineState (uint16_t state)
 Set control line states of USB CDC class Device (Virtual COM Port)
 
int32_t USBD_CDC_ACM_WriteData (int8_t instance, const uint8_t *buf, int32_t len)
 Write data from Communication Device to USB Host.
 
int USBD_CDC_ACM_PutChar (int8_t instance, int ch)
 Write a single character from Communication Device to USB Host.
 
int32_t USBD_CDC_ACM_ReadData (int8_t instance, uint8_t *buf, int32_t len)
 Read multiple data bytes received by Communication Device from USB Host.
 
int USBD_CDC_ACM_GetChar (int8_t instance)
 Read one character received by Communication Device from USB Host.
 
int32_t USBD_CDC_ACM_DataAvailable (int8_t instance)
 Retrieve number of data bytes received by Communication Device from USB Host that are available to read.
 
usbStatus USBD_CDC_ACM_Notify (int8_t instance, uint16_t state)
 Send notification of Communication Device status and line states to USB Host.
 
void USBD_CDC_ACM_DataReceived (int8_t instance, int32_t len)
 Callback function indicating new data was received by Communication Device from USB Host.
 

Description

The CDC class in the USB Component is used for data communication. It is typically used in applications that previously used a serial COM or UART communication.

Refer to:

The USB Component allows multiple instances of the CDC class. This feature is used to create USB Composite Devices. Each CDC class instance has a separate files and interface functions:

This documentation uses n as a placeholder for the instance number 0 - 3. Most applications only require one instance of a CDC class. For the first CDC class instance the instance number is 0:

To create an USB Device with a HID class:

Configuration File USBD_Config_CDC_n.h

The configuration file USBD_Config_CDC_n.h defines:

These settings are used to create the Interface Descriptor and Endpoint Descriptor of the related USB Device Class. It is important that the settings match the application specific behaviour in the related C source file USBD_User_CDC_n.c.

Software Structure

The handling for the CDC class endpoint events is implemented in USBD_CDC_Thread0 and USBD_CDC_Thread1 which is started by USBD_Initialize. Each instance of a CDC class runs an instance of USBD_CDC_Thread0 and USBD_CDC_Thread1.

The thread USBD_CDC_Thread0 handles Interrupt IN Endpoint whereas the USBD_CDC_Thread1 handles the Bulk IN/OUT Endpoint.

msc_inline_mscgraph_1

Code Example

The following source code is part of the user code template file. The application specific behaviour may be implemented using this code template.

#include "usb_cdc.h"
// Called during USBD_Initialize to initialize the USB Device class.
// ToDo: add code for initialization
}
// Called during USBD_Uninitialize to de-initialize the USB Device class.
// ToDo: add code for de-initialization
}
// Called upon USB Reset Event
void USBD_CDCn_ACM_Reset (void) {
// ToDo: add code for reset
}
// Called upon USB request to Set Line Coding.
// \param[in] line_coding pointer to \ref CDC_LINE_CODING structure.
// \return true set line coding request processed.
// \return false set line coding request not supported or not processed.
bool USBD_CDCn_ACM_SetLineCoding (CDC_LINE_CODING *line_coding) {
// ToDo: add code for set line coding
return true;
}
// Called upon USB request to Get Line Coding.
// \param[out] line_coding pointer to \ref CDC_LINE_CODING structure.
// \return true get line coding request processed.
// \return false get line coding request not supported or not processed.
bool USBD_CDCn_ACM_GetLineCoding (CDC_LINE_CODING *line_coding) {
// ToDo: add code for get line coding
return true;
}
// Called upon Set Control Line State request.
// \param [in] state control line settings bitmap.
// - bit 0: DTR state
// - bit 1: RTS state
// \return true set control line state request processed.
// \return false set control line state request not supported or not processed.
bool USBD_CDCn_ACM_SetControlLineState (uint16_t state) {
// ToDo: add code for set control line state
return true;
}

Function Documentation

int32_t USBD_CDC_ACM_DataAvailable ( int8_t  instance)

Retrieve number of data bytes received by Communication Device from USB Host that are available to read.

Parameters
[in]instanceinstance of CDC class.
Returns
number of bytes available to read.

The function USBD_CDC_ACM_DataAvailable returns the number of bytes available in the intermediate buffer received over the CDC device instance that is specified by the argument instance.

Code Example

// coming soon
void USBD_CDC_ACM_DataReceived ( int8_t  instance,
int32_t  len 
)

Callback function indicating new data was received by Communication Device from USB Host.

Parameters
[in]instanceinstance of CDC class.
[in]lennumber of bytes available to read.
Returns
none.

The function USBD_CDC_ACM_DataReceived reads the amount of bytes received from the CDC that is specified by the argument instance.

The argument len gives the amount of bytes that are available to be read.

Code Example

// coming soon
int USBD_CDC_ACM_GetChar ( int8_t  instance)

Read one character received by Communication Device from USB Host.

Parameters
[in]instanceinstance of CDC class.
Returns
value of read character or no character received.
  • value >= 0: value of first received unread character
  • value -1: indicates no character was received

The function USBD_CDC_ACM_GetChar reads a data character from the intermediate buffer that was received over the CDC device instance that is specified by the argument instance.

Code Example

// coming soon
usbStatus USBD_CDC_ACM_Notify ( int8_t  instance,
uint16_t  state 
)

Send notification of Communication Device status and line states to USB Host.

Parameters
[in]instanceinstance of CDC class.
[in]stateerror status and line states:
  • bit 6: bOverRun
  • bit 5: bParity
  • bit 4: bFraming
  • bit 3: bRingSignal
  • bit 2: bBreak
  • bit 1: bTxCarrier (DSR line state)
  • bit 0: bRxCarrier (DCD line state)
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBD_CDC_ACM_Notify sends error and line status information about the Virtual COM Port over the Interrupt endpoint.

The argument instance specifies the CDC device that is to be used with USBD_CDC_ACM_Notify.

The argument state specifies the error status and the line state.

Code Example

// coming soon
int USBD_CDC_ACM_PutChar ( int8_t  instance,
int  ch 
)

Write a single character from Communication Device to USB Host.

Parameters
[in]instanceinstance of CDC class.
[in]chcharacter to write.
Returns
value of accepted character or no character accepted.
  • value ch: if character accepted for writing
  • value -1: indicates character not accepted

The function USBD_CDC_ACM_PutChar asynchronously prepares a data byte that will be returned to the USB Host upon request.

The argument instance specifies the CDC class instance that is to be used.

The argument ch represents the character to be written.

Code Example

// coming soon
int32_t USBD_CDC_ACM_ReadData ( int8_t  instance,
uint8_t *  buf,
int32_t  len 
)

Read multiple data bytes received by Communication Device from USB Host.

Parameters
[in]instanceinstance of CDC class.
[out]bufbuffer that receives data.
[in]lenmaximum number of bytes to read.
Returns
number of bytes read or execution status.
  • value >= 0: number of bytes read
  • value < 0: error occurred, -value is execution status as defined with usbStatus

The function USBD_CDC_ACM_ReadData reads data from the intermediate buffer that was received over the Virtual COM Port and stores them into a buffer.

The argument instance specifies the CDC class instance that is to be used.

The argument buf is a pointer to the buffer containing the data to be read.

The argument len specifies the number of bytes to be read.

Code Example

// coming soon
int32_t USBD_CDC_ACM_WriteData ( int8_t  instance,
const uint8_t *  buf,
int32_t  len 
)

Write data from Communication Device to USB Host.

Parameters
[in]instanceinstance of CDC class.
[in]bufbuffer containing data bytes to write.
[in]lenmaximum number of bytes to write.
Returns
number of bytes accepted for writing or execution status.
  • value >= 0: number of bytes accepted for writing
  • value < 0: error occurred, -value is execution status as defined with usbStatus

The function USBD_CDC_ACM_WriteData asynchronously prepares data that will be returned to the USB Host upon request.

The argument instance specifies the CDC class instance that is to be used.

The argument buf is a pointer to the buffer containing the data to be written.

The argument len specifies the number of bytes to be sent.

Code Example

// coming soon
bool USBD_CDCn_ACM_GetLineCoding ( CDC_LINE_CODING *  line_coding)

Retrieve communication settings of USB CDC class Device (Virtual COM Port)

Parameters
[out]line_codingpointer to CDC_LINE_CODING structure.
Returns
true get line coding request processed.
false get line coding request not supported or not processed.

The function USBD_CDCn_ACM_GetLineCoding retrieves communication settings of the port used as the Virtual COM Port.

The argument line_coding is a pointer to the CDC Line Coding structure containing coding settings. Modify this function to the application needs.

Note
Callback when Get Line Coding request comes on Control Endpoint 0.

Code Example

// coming soon
void USBD_CDCn_ACM_Initialize ( void  )

Called during USBD_Initialize to initialize the USB CDC class Device (Virtual COM Port)

Returns
none.

The function USBD_CDCn_ACM_Initialize initializes the hardware resources of the port used as the Virtual COM Port. It is called during USBD_Initialize. The function may be used to allocate resources and initialize peripherals. Modify this function to the application needs.

Note
Remember to release used resources and de-initialize peripherals using USBD_CDCn_ACM_Uninitialize.

Code Example
The following code initializes an UART that is mapped as the Virtual COM Port to the CDC class.

UART_Initialize ();
}
void USBD_CDCn_ACM_Reset ( void  )

Called during USB Bus reset to reset the USB CDC class Device (Virtual COM Port)

Returns
none.

The function USBD_CDCn_ACM_Reset resets the internal states of the port used as the Virtual COM Port. Modify this function to the application's needs.

Code Example
The following code resets an UART that is mapped as the Virtual COM Port to the CDC class.

void USBD_CDCn_ACM_Reset (void) {
UART_Reset ();
}
bool USBD_CDCn_ACM_SetControlLineState ( uint16_t  state)

Set control line states of USB CDC class Device (Virtual COM Port)

Parameters
[in]statecontrol line settings bitmap.
  • bit 0: DTR state
  • bit 1: RTS state
Returns
true set control line state request processed.
false set control line state request not supported or not processed.

The function USBD_CDCn_ACM_SetControlLineState sets control line state on the port used as the Virtual COM Port.

The argument state represents control signal bitmap (0. bit - DTR line state, 1. bit - RTS line state). Modify this function to the application needs.

Note
Callback when Set Control Line State request comes on Control Endpoint 0.

Code Example
The following code outputs the line state to LEDs.

void USBD_CDCn_ACM_SetControlLineState (uint16_t state) {
((state & 1) ? (LED_On (0)) : (LED_Off (0)));
((state & 2) ? (LED_On (1)) : (LED_Off (1)));
return true;
}
bool USBD_CDCn_ACM_SetLineCoding ( CDC_LINE_CODING *  line_coding)

Change communication settings of USB CDC class Device (Virtual COM Port)

Parameters
[in]line_codingpointer to CDC_LINE_CODING structure.
Returns
true set line coding request processed.
false set line coding request not supported or not processed.

The function USBD_CDCn_ACM_SetLineCoding changes communication settings of the port used as the Virtual COM Port.

The argument line_coding is a pointer to the CDC Line Coding structure containing the requested coding settings. Modify this function to the application needs.

Note
Callback when Set Line Coding request comes on Control Endpoint 0.

Code Example
The following code configures an UART that is mapped as the Virtual COM Port to the CDC class.

void USBD_CDCn_ACM_SetLineCoding (CDC_LINE_CODING *line_coding) {
UART_Config.Baudrate = line_coding->dwDTERate;
UART_Config.DataBits = (UART_DataBits) line_coding->bDataBits;
UART_Config.Parity = (UART_Parity) line_coding->bParityType;
UART_Config.StopBits = (UART_StopBits) line_coding->bCharFormat;
UART_Config.FlowControl = UART_FLOW_CONTROL_RTS_CTS;
return true;
}
void USBD_CDCn_ACM_Uninitialize ( void  )

Called during USBD_Uninitialize to un-initialize the USB CDC class Device (Virtual COM Port)

Returns
none.

The function USBD_CDCn_ACM_Uninitialize uninitializes/releases the hardware resources of the port used as the Virtual COM Port. It is called during USBD_Uninitialize. If USBD_CDCn_ACM_Initialize has been adapted to the application, USBD_CDCn_ACM_Uninitialize should release resources and should de-initialize peripherals.

Code Example

UART_Uninitialize ();
}