USB CDC

About

USB Communications Device Class API. This class is used to enable communication between the host and the device.

This class is often used to enable serial communication and can be used to flash the firmware on the ESP32 without the external USB to Serial chip.

APIs

onEvent

Event handling functions.

void onEvent(esp_event_handler_t callback);

void onEvent(arduino_usb_cdc_event_t event, esp_event_handler_t callback);

Where event can be:

ARDUINO_USB_CDC_ANY_EVENT
ARDUINO_USB_CDC_CONNECTED_EVENT
ARDUINO_USB_CDC_DISCONNECTED_EVENT
ARDUINO_USB_CDC_LINE_STATE_EVENT
ARDUINO_USB_CDC_LINE_CODING_EVENT
ARDUINO_USB_CDC_RX_EVENT
ARDUINO_USB_CDC_TX_EVENT
ARDUINO_USB_CDC_RX_OVERFLOW_EVENT
ARDUINO_USB_CDC_MAX_EVENT

setRxBufferSize

The setRxBufferSize function is used to set the size of the RX buffer.

size_t setRxBufferSize(size_t size);

setTxTimeoutMs

This function is used to define the time to reach the timeout for the TX.

void setTxTimeoutMs(uint32_t timeout);

begin

This function is used to start the peripheral using the default CDC configuration.

void begin(unsigned long baud);

Where:

baud is the baud rate.

end

This function will finish the peripheral as CDC and release all the allocated resources. After calling end you need to use begin again in order to initialize the USB CDC driver again.

void end();

available

This function will return if there are messages in the queue.

int available(void);

The return is the number of bytes available to read.

availableForWrite

This function will return if the hardware is available to write data.

int availableForWrite(void);

peek

This function is used to peek messages from the queue.

int peek(void);

read

This function is used to read the bytes available.

size_t read(uint8_t *buffer, size_t size);

Where:

buffer is the pointer to the buffer to be read.
size is the number of bytes to be read.

write

This function is used to write the message.

size_t write(const uint8_t *buffer, size_t size);

Where:

buffer is the pointer to the buffer to be written.
size is the number of bytes to be written.

flush

This function is used to flush the data.

void flush(void);

baudRate

This function is used to get the baudRate.

uint32_t baudRate();

setDebugOutput

This function will enable the debug output, usually from the UART0, to the USB CDC.

void setDebugOutput(bool);

enableReboot

This function enables the device to reboot by the DTR as RTS signals.

void enableReboot(bool enable);

rebootEnabled

This function will return if the reboot is enabled.

bool rebootEnabled(void);

Example Code

Here is an example of how to use the USB CDC.

USBSerial

#ifndef ARDUINO_USB_MODE
#error This ESP32 SoC has no Native USB interface
#elif ARDUINO_USB_MODE == 1
#warning This sketch should be used when USB is in OTG mode
void setup() {}
void loop() {}
#else
#include "USB.h"

#if !ARDUINO_USB_CDC_ON_BOOT
USBCDC USBSerial;
#endif

static void usbEventCallback(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data) {
  if (event_base == ARDUINO_USB_EVENTS) {
    arduino_usb_event_data_t *data = (arduino_usb_event_data_t *)event_data;
    switch (event_id) {
      case ARDUINO_USB_STARTED_EVENT: Serial.println("USB PLUGGED"); break;
      case ARDUINO_USB_STOPPED_EVENT: Serial.println("USB UNPLUGGED"); break;
      case ARDUINO_USB_SUSPEND_EVENT: Serial.printf("USB SUSPENDED: remote_wakeup_en: %u\n", data->suspend.remote_wakeup_en); break;
      case ARDUINO_USB_RESUME_EVENT:  Serial.println("USB RESUMED"); break;

      default: break;
    }
  } else if (event_base == ARDUINO_USB_CDC_EVENTS) {
    arduino_usb_cdc_event_data_t *data = (arduino_usb_cdc_event_data_t *)event_data;
    switch (event_id) {
      case ARDUINO_USB_CDC_CONNECTED_EVENT:    Serial.println("CDC CONNECTED"); break;
      case ARDUINO_USB_CDC_DISCONNECTED_EVENT: Serial.println("CDC DISCONNECTED"); break;
      case ARDUINO_USB_CDC_LINE_STATE_EVENT:   Serial.printf("CDC LINE STATE: dtr: %u, rts: %u\n", data->line_state.dtr, data->line_state.rts); break;
      case ARDUINO_USB_CDC_LINE_CODING_EVENT:
        Serial.printf(
          "CDC LINE CODING: bit_rate: %lu, data_bits: %u, stop_bits: %u, parity: %u\n", data->line_coding.bit_rate, data->line_coding.data_bits,
          data->line_coding.stop_bits, data->line_coding.parity
        );
        break;
      case ARDUINO_USB_CDC_RX_EVENT:
        Serial.printf("CDC RX [%u]:", data->rx.len);
        {
          uint8_t buf[data->rx.len];
          size_t len = USBSerial.read(buf, data->rx.len);
          Serial.write(buf, len);
        }
        Serial.println();
        break;
      case ARDUINO_USB_CDC_RX_OVERFLOW_EVENT: Serial.printf("CDC RX Overflow of %d bytes", data->rx_overflow.dropped_bytes); break;

      default: break;
    }
  }
}

void setup() {
  Serial.begin(115200);
  Serial.setDebugOutput(true);

  USB.onEvent(usbEventCallback);
  USBSerial.onEvent(usbEventCallback);

  USBSerial.begin();
  USB.begin();
}

void loop() {
  while (Serial.available()) {
    size_t l = Serial.available();
    uint8_t b[l];
    l = Serial.read(b, l);
    USBSerial.write(b, l);
  }
}
#endif /* ARDUINO_USB_MODE */