User API reference of the Communication Device Class (ACM). More...

Functions
void	USBD_CDCn_ACM_Initialize (void)
	Callback function called during USBD_Initialize to initialize the USB CDC class instance (ACM)

void	USBD_CDCn_ACM_Uninitialize (void)
	Callback function called during USBD_Uninitialize to de-initialize the USB CDC class instance (ACM)

void	USBD_CDCn_ACM_Reset (void)
	Callback function called upon USB Bus Reset signaling.

bool	USBD_CDCn_ACM_SendEncapsulatedCommand (const uint8_t *buf, uint16_t len)
	Callback function called upon reception of request send encapsulated command sent by the USB Host.

bool	USBD_CDCn_ACM_GetEncapsulatedResponse (uint16_t max_len, uint8_t *buf, uint16_t len)
	Callback function called upon reception of request to get encapsulated response sent by the USB Host.

bool	USBD_CDCn_ACM_SetLineCoding (const CDC_LINE_CODING *line_coding)
	Callback function called upon USB Host request to change communication settings.

bool	USBD_CDCn_ACM_GetLineCoding (CDC_LINE_CODING *line_coding)
	Callback function called upon USB Host request to retrieve communication settings.

bool	USBD_CDCn_ACM_SetControlLineState (uint16_t state)
	Callback function called upon USB Host request to set control line states.

void	USBD_CDCn_ACM_DataReceived (uint32_t len)
	Callback function called when new data was received.

void	USBD_CDCn_ACM_DataSent (void)
	Callback function called when all data was sent.

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_SerialState (uint8_t instance, uint16_t state)
	Send notification of Communication Device status and line states to USB Host.

usbStatus	USBD_CDC_ACM_Notify_ResponseAvailable (uint8_t instance)
	Send notification to USB Host signaling that response is available.

Description

User API reference of the Communication Device Class (ACM).

Function Documentation

◆ USBD_CDC_ACM_DataAvailable()

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.

◆ USBD_CDC_ACM_GetChar()

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.

◆ USBD_CDC_ACM_Notify_ResponseAvailable()

usbStatus USBD_CDC_ACM_Notify_ResponseAvailable ( uint8_t instance )

Send notification to USB Host signaling that response is available.

Parameters

[in] instance instance of CDC class.

Returns: status code that indicates the execution status of the function as defined with usbStatus.

The function USBD_CDC_ACM_Notify_ResponseAvailable sends notification that response is available over the Interrupt Endpoint.

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

◆ USBD_CDC_ACM_Notify_SerialState()

usbStatus USBD_CDC_ACM_Notify_SerialState	(	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_SerialState 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_SerialState.

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

Note: Bits 0 (bRxCarrier) and 1 (bTxCarrier) are consistent states signals and notify should be called whenever their state changes. For all other bits the notify should be called only when respective state has been activated or error has occurred.

◆ USBD_CDC_ACM_PutChar()

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.

◆ USBD_CDC_ACM_ReadData()

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.

◆ USBD_CDC_ACM_WriteData()

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

◆ USBD_CDCn_ACM_DataReceived()

void USBD_CDCn_ACM_DataReceived ( uint32_t len )

Callback function called when new data was received.

Parameters

[in] len number of bytes available to read.

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.

◆ USBD_CDCn_ACM_DataSent()

void USBD_CDCn_ACM_DataSent ( void )

Callback function called when all data was sent.

The function USBD_CDCn_ACM_DataSent notifies that all data was sent.

Note: Callback when all data was sent on Bulk IN Endpoint.

◆ USBD_CDCn_ACM_GetEncapsulatedResponse()

bool USBD_CDCn_ACM_GetEncapsulatedResponse	(	uint16_t	max_len,
		uint8_t **	buf,
		uint16_t *	len
	)

Callback function called upon reception of request to get encapsulated response sent by the USB Host.

Parameters

[in]	max_len	maximum number of data bytes that USB Host expects to receive.
[out]	buf	pointer to buffer containing get encapsulated response to be returned to USB Host.
[out]	len	pointer to number of data bytes to be returned to USB Host.

Returns

received get encapsulated response processed status :

value true : processed and response prepared
value false : not processed

The function USBD_CDCn_ACM_GetEncapsulatedResponse is used for transferring data from standard CDC ACM USB Device to USB Host, and content of data is specified by protocol used. This command is used for RNDIS device in which case protocol is Vendor-specific and specified by Remote Network Driver Interface Specification.

The argument max_len is a maximum number of bytes that USB Host expects to receive.

The argument buf is a pointer to the buffer containing response to get encapsulated response request to be sent by the USB Device.

The argument len is a pointer to number of bytes, that encapsulated response data contains, and will be returned to USB Host.

Modify this function to the application needs.

Note: Callback when Get Encapsulated Response request comes on Control Endpoint 0.

◆ USBD_CDCn_ACM_GetLineCoding()

bool USBD_CDCn_ACM_GetLineCoding ( CDC_LINE_CODING * line_coding )

Callback function called upon USB Host request to retrieve communication settings.

Parameters

[out] line_coding pointer to CDC_LINE_CODING structure.

Returns

get line coding request processed status :

value true : processed
value false : 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.

◆ USBD_CDCn_ACM_Initialize()

void USBD_CDCn_ACM_Initialize ( void )

Callback function called during USBD_Initialize to initialize the USB CDC class instance (ACM)

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's 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 ();
}  

◆ USBD_CDCn_ACM_Reset()

void USBD_CDCn_ACM_Reset ( void )

Callback function called upon USB Bus Reset signaling.

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 ();
}  

◆ USBD_CDCn_ACM_SendEncapsulatedCommand()

bool USBD_CDCn_ACM_SendEncapsulatedCommand	(	const uint8_t *	buf,
		uint16_t	len
	)

Callback function called upon reception of request send encapsulated command sent by the USB Host.

Parameters

[in]	buf	buffer that contains send encapsulated command request.
[in]	len	length of send encapsulated command request.

Returns

received send encapsulated command processed status :

value true : processed
value false : not processed

The function USBD_CDCn_ACM_SendEncapsulatedCommand is used for transferring data from USB Host to standard CDC ACM USB Device, and content of data is specified by protocol used. This command is used for RNDIS device in which case protocol is Vendor-specific and specified by Remote Network Driver Interface Specification.

The argument buf is a pointer to the encapsulated command request received by the USB Device.

The argument len is number of bytes, that encapsulated command data contains, and is available for reading.

Modify this function to the application needs.

Note: Callback when Send Encapsulated Command request comes on Control Endpoint 0.

◆ USBD_CDCn_ACM_SetControlLineState()

bool USBD_CDCn_ACM_SetControlLineState ( uint16_t state )

Callback function called upon USB Host request to set control line states.

Parameters

[in]

state

control line settings bitmap :

bit 0 : DTR state
bit 1 : RTS state

Returns

set control line state request processed status :

value true : processed
value false : 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;
}

◆ USBD_CDCn_ACM_SetLineCoding()

bool USBD_CDCn_ACM_SetLineCoding ( const CDC_LINE_CODING * line_coding )

Callback function called upon USB Host request to change communication settings.

Parameters

[in] line_coding pointer to CDC_LINE_CODING structure.

Returns

set line coding request processed status :

value true : processed
value false : 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 (const 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;
}

◆ USBD_CDCn_ACM_Uninitialize()

void USBD_CDCn_ACM_Uninitialize ( void )

Callback function called during USBD_Uninitialize to de-initialize the USB CDC class instance (ACM)

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 ();
}

Functions

Description

Function Documentation

◆ USBD_CDC_ACM_DataAvailable()

◆ USBD_CDC_ACM_GetChar()

◆ USBD_CDC_ACM_Notify_ResponseAvailable()

◆ USBD_CDC_ACM_Notify_SerialState()

◆ USBD_CDC_ACM_PutChar()

◆ USBD_CDC_ACM_ReadData()

◆ USBD_CDC_ACM_WriteData()

◆ USBD_CDCn_ACM_DataReceived()

◆ USBD_CDCn_ACM_DataSent()

◆ USBD_CDCn_ACM_GetEncapsulatedResponse()

◆ USBD_CDCn_ACM_GetLineCoding()

◆ USBD_CDCn_ACM_Initialize()

◆ USBD_CDCn_ACM_Reset()

◆ USBD_CDCn_ACM_SendEncapsulatedCommand()

◆ USBD_CDCn_ACM_SetControlLineState()

◆ USBD_CDCn_ACM_SetLineCoding()

◆ USBD_CDCn_ACM_Uninitialize()