USB Component  Version 6.13.7
MDK Middleware for USB Device and Host Communication
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages

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) More...
 
void USBD_CDCn_ACM_Uninitialize (void)
 Callback function called during USBD_Uninitialize to de-initialize the USB CDC class instance (ACM) More...
 
void USBD_CDCn_ACM_Reset (void)
 Callback function called upon USB Bus Reset signaling. More...
 
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. More...
 
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. More...
 
bool USBD_CDCn_ACM_SetLineCoding (const CDC_LINE_CODING *line_coding)
 Callback function called upon USB Host request to change communication settings. More...
 
bool USBD_CDCn_ACM_GetLineCoding (CDC_LINE_CODING *line_coding)
 Callback function called upon USB Host request to retrieve communication settings. More...
 
bool USBD_CDCn_ACM_SetControlLineState (uint16_t state)
 Callback function called upon USB Host request to set control line states. More...
 
void USBD_CDCn_ACM_DataReceived (uint32_t len)
 Callback function called when new data was received. More...
 
void USBD_CDCn_ACM_DataSent (void)
 Callback function called when all data was sent. More...
 
int32_t USBD_CDC_ACM_WriteData (uint8_t instance, const uint8_t *buf, int32_t len)
 Write data from Communication Device to USB Host. More...
 
int USBD_CDC_ACM_PutChar (uint8_t instance, int ch)
 Write a single character from Communication Device to USB Host. More...
 
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. More...
 
int USBD_CDC_ACM_GetChar (uint8_t instance)
 Read one character received by Communication Device from USB Host. More...
 
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. More...
 
usbStatus USBD_CDC_ACM_Notify_SerialState (uint8_t instance, uint16_t state)
 Send notification of Communication Device status and line states to USB Host. More...
 
usbStatus USBD_CDC_ACM_Notify_ResponseAvailable (uint8_t instance)
 Send notification to USB Host signaling that response is available. More...
 

Description

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

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

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

usbStatus USBD_CDC_ACM_Notify_ResponseAvailable ( uint8_t  instance)

Send notification to USB Host signaling that response is available.

Parameters
[in]instanceinstance 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.

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]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_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.
int USBD_CDC_ACM_PutChar ( uint8_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.

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

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]instanceinstance of CDC class.
[in]bufbuffer containing data bytes to write.
[in]lennumber 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.

void USBD_CDCn_ACM_DataReceived ( uint32_t  len)

Callback function called when new data was received.

Parameters
[in]lennumber 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  )

Callback function called when all data was sent.

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_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_lenmaximum number of data bytes that USB Host expects to receive.
[out]bufpointer to buffer containing get encapsulated response to be returned to USB Host.
[out]lenpointer 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.
bool USBD_CDCn_ACM_GetLineCoding ( CDC_LINE_CODING line_coding)

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

Parameters
[out]line_codingpointer 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.
void USBD_CDCn_ACM_Initialize ( void  )

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

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

UART_Initialize ();
}
void USBD_CDCn_ACM_Reset ( void  )

Callback function called upon USB Bus Reset signaling.

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_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]bufbuffer that contains send encapsulated command request.
[in]lenlength 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.
bool USBD_CDCn_ACM_SetControlLineState ( uint16_t  state)

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

Parameters
[in]statecontrol 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;
}
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_codingpointer 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;
}
void USBD_CDCn_ACM_Uninitialize ( void  )

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

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

UART_Uninitialize ();
}