CDC: Communication Device Class Functions

Implement application specific behaviour of a Communication Device Class (CDC) USB Device. More...

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 de-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)
void	USBD_CDCn_ACM_DataReceived (uint32_t len)
	Function indicating new data was received by USB CDC class Device (Virtual COM Port)
void	USBD_CDCn_ACM_DataSent (void)
	Function indicating all data was sent by USB CDC class Device (Virtual COM Port)
int32_t	USBD_CDC_ACM_WriteData (uint8_t instance, const uint8_t *buf, int32_t len)
	Write data from Communication Device to USB Host.
int	USBD_CDC_ACM_PutChar (uint8_t instance, int ch)
	Write a single character from Communication Device to USB Host.
int32_t	USBD_CDC_ACM_ReadData (uint8_t instance, uint8_t *buf, int32_t len)
	Read multiple data bytes received by Communication Device from USB Host.
int	USBD_CDC_ACM_GetChar (uint8_t instance)
	Read one character received by Communication Device from USB Host.
int32_t	USBD_CDC_ACM_DataAvailable (uint8_t instance)
	Retrieve number of data bytes received by Communication Device from USB Host that are available to read.
usbStatus	USBD_CDC_ACM_Notify (uint8_t instance, uint16_t state)
	Send notification of Communication Device status and line states to USB Host.

Description

Implement application specific behaviour of a Communication Device Class (CDC) USB Device.

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:

• CDC: Communication Device Class for an overview of the CDC class.
• USB Device Virtual COM Port for example projects that use the CDC class.

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:

• A configuration file USBD_Config_CDC_n.h.
• A application specific user source code file which may be implemented with the user code template USBD_User_CDC_n.c.
• Functions that start with the prefix USBD_CDCn_ are available for each instance of a CDC class.

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:

• USBD_Config_CDC_0.h
• USBD_User_CDC_0.c
• The function prefix is USBD_CDC0_

Software Structure

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

The thread USBD_CDCn_Int_Thread handles Interrupt IN Endpoint whereas the USBD_CDCn_Bulk_Thread handles the Bulk IN and Bulk OUT Endpoints.

Implementation

To create an USB Device with a CDC class:

• Set the required number for USB:Device:CDC class instances during the RTE Component Selection.
• Add the related user code template file.
• Implement the application specific behaviour in USBD_User_CDC_n.c.
• Set the parameters in the configuration file USBD_Config_CDC_n.c.

Configuration File USBD_Config_CDC_n.h

The configuration file USBD_Config_CDC_n.h defines:

• The assignment of the CDC class to the USB Device instance.
• USB Endpoint assignments for the CDC class with parameters for Full/Low-speed and High-speed communication.
• Class Settings for the Interface Descriptor.

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 behavior in the related C source file USBD_User_CDC_n.c.

User Code Template The USBD_User_CDC.c user code template contains all the callback functions that need to be implemented by the user.

User Code Template USBD_User_CDC.c

The following source code can be used to implement the application specific behavior of an USB CDC Device.

/*------------------------------------------------------------------------------
 * MDK Middleware - Component ::USB:Device
 * Copyright (c) 2004-2014 ARM Germany GmbH. All rights reserved.
 *------------------------------------------------------------------------------
 * Name:    USBD_User_CDC_n.c
 * Purpose: USB Device Communication Device Class (CDC) User module
 * Rev.:    V6.2
 *----------------------------------------------------------------------------*/

 
#include <stdbool.h>
#include "rl_usb.h"
 
// Called during USBD_Initialize to initialize the USB Device class.
void USBD_CDCn_ACM_Initialize (void) {
  // Add code for initialization
}
 
 
// Called during USBD_Uninitialize to de-initialize the USB Device class.
void USBD_CDCn_ACM_Uninitialize (void) {
  // Add code for de-initialization
}
 
 
// Called upon USB Reset Event
void USBD_CDCn_ACM_Reset (void) {
  // 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) {
  // 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) {
  // 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) {
  // Add code for set control line state
 
  return true;
}
 

Function Documentation

int32_t USBD_CDC_ACM_DataAvailable

(

uint8_t

instance

)

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

Parameters

[in]

instance

instance 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 that was received from the USB Host by the CDC device instance that is specified by the argument instance.

Code Example

// coming soon

int USBD_CDC_ACM_GetChar

(

uint8_t

instance

)

Read one character received by Communication Device from USB Host.

Parameters

[in]

instance

instance 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 from the USB Host by the CDC device instance that is specified by the argument instance.

Code Example

// coming soon

usbStatus USBD_CDC_ACM_Notify	(	uint8_t	instance,
		uint16_t	state
	)

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

Parameters

[in]	instance	instance of CDC class.
[in]	state	error 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	(	uint8_t	instance,
		int	ch
	)

Write a single character from Communication Device to USB Host.

Parameters

[in]	instance	instance of CDC class.
[in]	ch	character 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	(	uint8_t	instance,
		uint8_t *	buf,
		int32_t	len
	)

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

Parameters

[in]	instance	instance of CDC class.
[out]	buf	buffer that receives data.
[in]	len	maximum 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 from the USB Host 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 where received data will be stored.

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

Code Example

// coming soon

int32_t USBD_CDC_ACM_WriteData	(	uint8_t	instance,
		const uint8_t *	buf,
		int32_t	len
	)

Write data from Communication Device to USB Host.

Parameters

[in]	instance	instance of CDC class.
[in]	buf	buffer containing data bytes to write.
[in]	len	maximum 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 written.

Code Example

// coming soon

void USBD_CDCn_ACM_DataReceived

(

uint32_t

len

)

Function indicating new data was received by USB CDC class Device (Virtual COM Port)

Parameters

[in]

len

number of bytes available to read.

Returns

none.

The function USBD_CDCn_ACM_DataReceived notifies that there is newly received data available.

The argument len is number of bytes available to read. Modify this function to the application needs.

Note

Callback when new data is received on Bulk OUT Endpoint.

void USBD_CDCn_ACM_DataSent

(

void

)

Function indicating all data was sent by USB CDC class Device (Virtual COM Port)

Returns

none.

The function USBD_CDCn_ACM_DataSent notifies that all data was sent.

Note

Callback when all data was sent on Bulk IN Endpoint.

bool USBD_CDCn_ACM_GetLineCoding

(

CDC_LINE_CODING *

line_coding

)

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

Parameters

[out]

line_coding

pointer 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.

bool USBD_CDCn_ACM_Initialize (void) {
 
  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]

state

control 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_coding

pointer 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 de-initialize the USB CDC class Device (Virtual COM Port)

Returns

none.

The function USBD_CDCn_ACM_Uninitialize de-initializes/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

bool USBD_CDCn_ACM_Uninitialize (void) {
 
  UART_Uninitialize ();
}