tusb_cdc_acm.h File Reference

#include <stdint.h>
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "freertos/timers.h"
#include "tusb.h"
#include "tinyusb.h"

Include dependency graph for tusb_cdc_acm.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	cdcacm_event_rx_wanted_char_data_t
	Data provided to the input of the callback_rx_wanted_char callback. More...
struct	cdcacm_event_line_state_changed_data_t
	Data provided to the input of the callback_line_state_changed callback. More...
struct	cdcacm_event_line_coding_changed_data_t
	Data provided to the input of the line_coding_changed callback. More...
struct	cdcacm_event_t
	Describes an event passing to the input of a callbacks. More...
struct	tinyusb_config_cdcacm_t
	Configuration structure for CDC-ACM. More...

Typedefs
typedef void(*	tusb_cdcacm_callback_t) (int itf, cdcacm_event_t *event)
	CDC-ACM callback type.

Enumerations
enum	tinyusb_cdcacm_itf_t { TINYUSB_CDC_ACM_0 = 0x0 , TINYUSB_CDC_ACM_1 , TINYUSB_CDC_ACM_MAX }
	CDC ports available to setup. More...
enum	cdcacm_event_type_t { CDC_EVENT_RX , CDC_EVENT_RX_WANTED_CHAR , CDC_EVENT_LINE_STATE_CHANGED , CDC_EVENT_LINE_CODING_CHANGED }
	Types of CDC ACM events. More...

Functions
esp_err_t	tusb_cdc_acm_init (const tinyusb_config_cdcacm_t *cfg)
	Initialize CDC ACM. Initialization will be finished with the tud_cdc_line_state_cb callback.
esp_err_t	tinyusb_cdcacm_register_callback (tinyusb_cdcacm_itf_t itf, cdcacm_event_type_t event_type, tusb_cdcacm_callback_t callback)
	Register a callback invoking on CDC event. If the callback had been already registered, it will be overwritten.
esp_err_t	tinyusb_cdcacm_unregister_callback (tinyusb_cdcacm_itf_t itf, cdcacm_event_type_t event_type)
	Unregister a callback invoking on CDC event.
size_t	tinyusb_cdcacm_write_queue_char (tinyusb_cdcacm_itf_t itf, char ch)
	Sent one character to a write buffer.
size_t	tinyusb_cdcacm_write_queue (tinyusb_cdcacm_itf_t itf, const uint8_t *in_buf, size_t in_size)
	Write data to write buffer from a byte array.
esp_err_t	tinyusb_cdcacm_write_flush (tinyusb_cdcacm_itf_t itf, uint32_t timeout_ticks)
	Send all data from a write buffer. Use tinyusb_cdcacm_write_queue to add data to the buffer.
esp_err_t	tinyusb_cdcacm_read (tinyusb_cdcacm_itf_t itf, uint8_t *out_buf, size_t out_buf_sz, size_t *rx_data_size)
	Read a content to the array, and defines it's size to the sz_store.
bool	tusb_cdc_acm_initialized (tinyusb_cdcacm_itf_t itf)
	Check if the ACM initialized.

Typedef Documentation

tusb_cdcacm_callback_t

typedef void(* tusb_cdcacm_callback_t) (int itf, cdcacm_event_t *event)

CDC-ACM callback type.

Definition at line 79 of file tusb_cdc_acm.h.

Enumeration Type Documentation

cdcacm_event_type_t

enum cdcacm_event_type_t

Types of CDC ACM events.

Enumerator
CDC_EVENT_RX
CDC_EVENT_RX_WANTED_CHAR
CDC_EVENT_LINE_STATE_CHANGED
CDC_EVENT_LINE_CODING_CHANGED

Definition at line 57 of file tusb_cdc_acm.h.

             {
    CDC_EVENT_RX,
    CDC_EVENT_RX_WANTED_CHAR,
    CDC_EVENT_LINE_STATE_CHANGED,
    CDC_EVENT_LINE_CODING_CHANGED
} cdcacm_event_type_t;

tinyusb_cdcacm_itf_t

enum tinyusb_cdcacm_itf_t

CDC ports available to setup.

Enumerator
TINYUSB_CDC_ACM_0
TINYUSB_CDC_ACM_1
TINYUSB_CDC_ACM_MAX

Definition at line 23 of file tusb_cdc_acm.h.

             {
    TINYUSB_CDC_ACM_0 = 0x0,
    TINYUSB_CDC_ACM_1,
    TINYUSB_CDC_ACM_MAX
} tinyusb_cdcacm_itf_t;

Function Documentation

tinyusb_cdcacm_read()

esp_err_t tinyusb_cdcacm_read	(	tinyusb_cdcacm_itf_t	itf,
		uint8_t *	out_buf,
		size_t	out_buf_sz,
		size_t *	rx_data_size )

Read a content to the array, and defines it's size to the sz_store.

Parameters

itf	- number of a CDC object
out_buf	- to this array will be stored the object from a CDC buffer
out_buf_sz	- size of buffer for results
rx_data_size	- to this address will be stored the object's size

Returns

esp_err_t ESP_OK, ESP_FAIL or ESP_ERR_INVALID_STATE

Definition at line 247 of file tusb_cdc_acm.c.

{
    esp_tusb_cdcacm_t *acm = get_acm(itf);
    ESP_RETURN_ON_FALSE(acm, ESP_ERR_INVALID_STATE, TAG, "Interface is not initialized. Use `tinyusb_cdc_init` for initialization");
    size_t read_sz;
 
    /* Take a mutex to proceed two uninterrupted read operations */
    ESP_RETURN_ON_ERROR(ringbuf_mux_take(acm), TAG, "ringbuf_mux_take failed");
 
    esp_err_t res = read_from_rx_unread_to_buffer(acm, out_buf, out_buf_sz, &read_sz);
    if (res != ESP_OK) {
        ESP_RETURN_ON_ERROR(ringbuf_mux_give(acm), TAG, "ringbuf_mux_give failed");
        return res;
    }
 
    *rx_data_size = read_sz;
    /* Buffer's data can be wrapped, at that situations we should make another retrievement */
    if (read_from_rx_unread_to_buffer(acm, out_buf + read_sz, out_buf_sz - read_sz, &read_sz) == ESP_OK) {
        *rx_data_size += read_sz;
    }
 
    ESP_RETURN_ON_ERROR(ringbuf_mux_give(acm), TAG, "ringbuf_mux_give failed");
    return ESP_OK;
}

References ESP_OK, ESP_RETURN_ON_ERROR, get_acm(), read_from_rx_unread_to_buffer(), ringbuf_mux_give(), ringbuf_mux_take(), and TAG.

Here is the call graph for this function:

tinyusb_cdcacm_register_callback()

esp_err_t tinyusb_cdcacm_register_callback	(	tinyusb_cdcacm_itf_t	itf,
		cdcacm_event_type_t	event_type,
		tusb_cdcacm_callback_t	callback )

Register a callback invoking on CDC event. If the callback had been already registered, it will be overwritten.

Parameters

itf	- number of a CDC object
event_type	- type of registered event for a callback
callback	- callback function

Returns

esp_err_t - ESP_OK or ESP_ERR_INVALID_ARG

Definition at line 159 of file tusb_cdc_acm.c.

{
    esp_tusb_cdcacm_t *acm = get_acm(itf);
    if (acm) {
        switch (event_type) {
        case CDC_EVENT_RX:
            acm->callback_rx = callback;
            return ESP_OK;
        case CDC_EVENT_RX_WANTED_CHAR:
            acm->callback_rx_wanted_char = callback;
            return ESP_OK;
        case CDC_EVENT_LINE_STATE_CHANGED:
            acm->callback_line_state_changed = callback;
            return ESP_OK;
        case CDC_EVENT_LINE_CODING_CHANGED:
            acm->callback_line_coding_changed = callback;
            return ESP_OK;
        default:
            ESP_LOGE(TAG, "Wrong event type");
            return ESP_ERR_INVALID_ARG;
        }
    } else {
        ESP_LOGE(TAG, "CDC-ACM is not initialized");
        return ESP_ERR_INVALID_STATE;
    }
}

References esp_tusb_cdcacm_t::callback_line_coding_changed, esp_tusb_cdcacm_t::callback_line_state_changed, esp_tusb_cdcacm_t::callback_rx, esp_tusb_cdcacm_t::callback_rx_wanted_char, CDC_EVENT_LINE_CODING_CHANGED, CDC_EVENT_LINE_STATE_CHANGED, CDC_EVENT_RX, CDC_EVENT_RX_WANTED_CHAR, ESP_OK, get_acm(), and TAG.

Referenced by tusb_cdc_acm_init().

Here is the call graph for this function:

Here is the caller graph for this function:

tinyusb_cdcacm_unregister_callback()

esp_err_t tinyusb_cdcacm_unregister_callback	(	tinyusb_cdcacm_itf_t	itf,
		cdcacm_event_type_t	event_type )

Unregister a callback invoking on CDC event.

Parameters

itf	- number of a CDC object
event_type	- type of registered event for a callback

Returns

esp_err_t - ESP_OK or ESP_ERR_INVALID_ARG

Definition at line 188 of file tusb_cdc_acm.c.

{
    esp_tusb_cdcacm_t *acm = get_acm(itf);
    if (!acm) {
        ESP_LOGE(TAG, "Interface is not initialized. Use `tinyusb_cdc_init` for initialization");
        return ESP_ERR_INVALID_STATE;
    }
    switch (event_type) {
    case CDC_EVENT_RX:
        acm->callback_rx = NULL;
        return ESP_OK;
    case CDC_EVENT_RX_WANTED_CHAR:
        acm->callback_rx_wanted_char = NULL;
        return ESP_OK;
    case CDC_EVENT_LINE_STATE_CHANGED:
        acm->callback_line_state_changed = NULL;
        return ESP_OK;
    case CDC_EVENT_LINE_CODING_CHANGED:
        acm->callback_line_coding_changed = NULL;
        return ESP_OK;
    default:
        ESP_LOGE(TAG, "Wrong event type");
        return ESP_ERR_INVALID_ARG;
    }
}

References esp_tusb_cdcacm_t::callback_line_coding_changed, esp_tusb_cdcacm_t::callback_line_state_changed, esp_tusb_cdcacm_t::callback_rx, esp_tusb_cdcacm_t::callback_rx_wanted_char, CDC_EVENT_LINE_CODING_CHANGED, CDC_EVENT_LINE_STATE_CHANGED, CDC_EVENT_RX, CDC_EVENT_RX_WANTED_CHAR, ESP_OK, get_acm(), and TAG.

Here is the call graph for this function:

tinyusb_cdcacm_write_flush()

esp_err_t tinyusb_cdcacm_write_flush	(	tinyusb_cdcacm_itf_t	itf,
		uint32_t	timeout_ticks )

Send all data from a write buffer. Use tinyusb_cdcacm_write_queue to add data to the buffer.

   WARNING! TinyUSB can block output Endpoint for several RX callbacks, after will do additional flush
   after the each trasfer. That can leads to the situation when you requested a flush, but it will fail until
   ont of the next callbacks ends.
   SO USING OF THE FLUSH WITH TIMEOUTS IN CALLBACKS IS NOT RECOMENDED - YOU CAN GET A LOCK FOR THE TIMEOUT

Parameters

itf	- number of a CDC object
timeout_ticks	- waiting until flush will be considered as failed

Returns

esp_err_t - ESP_OK if (timeout_ticks > 0) and and flush was successful, ESP_ERR_TIMEOUT if timeout occurred3 or flush was successful with (timeout_ticks == 0) ESP_FAIL if flush was unsuccessful

Definition at line 294 of file tusb_cdc_acm.c.

{
    if (!get_acm(itf)) { // non-initialized
        return ESP_FAIL;
    }
 
    if (!timeout_ticks) { // if no timeout - nonblocking mode
        int res = tud_cdc_n_write_flush(itf);
        if (!res) {
            ESP_LOGW(TAG, "flush failed (res: %d)", res);
            return ESP_FAIL;
        } else {
            if (tud_cdc_n_write_occupied(itf)) {
                ESP_LOGW(TAG, "remained data to flush!");
                return ESP_FAIL;
            } else {
                return ESP_OK;
            }
        }
    } else { // trying during the timeout
        uint32_t ticks_start = xTaskGetTickCount();
        uint32_t ticks_now = ticks_start;
        while (1) { // loop until success or until the time runs out
            ticks_now = xTaskGetTickCount();
            if (!tud_cdc_n_write_occupied(itf)) { // if nothing to write - nothing to flush
                break;
            }
            if (tud_cdc_n_write_flush(itf)) { // Success
                break;
            }
            if ( (ticks_now - ticks_start) > timeout_ticks ) { // Time is up
                ESP_LOGW(TAG, "Flush failed");
                return ESP_ERR_TIMEOUT;
            }
            vTaskDelay(1);
        }
        return ESP_OK;
    }
}

References ESP_OK, get_acm(), TAG, and tud_cdc_n_write_occupied().

Referenced by safe_cdcacm_write_flush().

Here is the call graph for this function:

Here is the caller graph for this function:

tinyusb_cdcacm_write_queue()

size_t tinyusb_cdcacm_write_queue	(	tinyusb_cdcacm_itf_t	itf,
		const uint8_t *	in_buf,
		size_t	in_size )

Write data to write buffer from a byte array.

Parameters

itf	- number of a CDC object
in_buf	- a source array
in_size	- size to write from arr_src

Returns

size_t - amount of queued bytes

Definition at line 280 of file tusb_cdc_acm.c.

{
    if (!get_acm(itf)) { // non-initialized
        return 0;
    }
    const uint32_t size_available = tud_cdc_n_write_available(itf);
    return tud_cdc_n_write(itf, in_buf, MIN(in_size, size_available));
}

References get_acm(), and MIN.

Referenced by cdc_tx_task().

Here is the call graph for this function:

Here is the caller graph for this function:

tinyusb_cdcacm_write_queue_char()

size_t tinyusb_cdcacm_write_queue_char	(	tinyusb_cdcacm_itf_t	itf,
		char	ch )

Sent one character to a write buffer.

Parameters

itf	- number of a CDC object
ch	- character to send

Returns

size_t - amount of queued bytes

Definition at line 272 of file tusb_cdc_acm.c.

{
    if (!get_acm(itf)) { // non-initialized
        return 0;
    }
    return tud_cdc_n_write_char(itf, ch);
}

References get_acm().

Referenced by tusb_write().

Here is the call graph for this function:

Here is the caller graph for this function:

tusb_cdc_acm_init()

esp_err_t tusb_cdc_acm_init

(

const tinyusb_config_cdcacm_t *

cfg

)

Initialize CDC ACM. Initialization will be finished with the tud_cdc_line_state_cb callback.

Parameters

cfg	- init configuration structure

Returns

esp_err_t

Definition at line 352 of file tusb_cdc_acm.c.

{
    esp_err_t ret = ESP_OK;
    int itf = (int)cfg->cdc_port;
    /* Creating a CDC object */
    const tinyusb_config_cdc_t cdc_cfg = {
        .usb_dev = cfg->usb_dev,
        .cdc_class = TUSB_CLASS_CDC,
        .cdc_subclass.comm_subclass = CDC_COMM_SUBCLASS_ABSTRACT_CONTROL_MODEL
    };
 
    ESP_RETURN_ON_ERROR(tinyusb_cdc_init(itf, &cdc_cfg), TAG, "tinyusb_cdc_init failed");
    ESP_GOTO_ON_FALSE(!alloc_obj(itf), ESP_FAIL, out4, TAG, "alloc_obj failed");
 
    /* Callbacks setting up*/
    if (cfg->callback_rx) {
        tinyusb_cdcacm_register_callback(itf, CDC_EVENT_RX, cfg->callback_rx);
    }
    if (cfg->callback_rx_wanted_char) {
        tinyusb_cdcacm_register_callback(itf, CDC_EVENT_RX_WANTED_CHAR, cfg->callback_rx_wanted_char);
    }
    if (cfg->callback_line_state_changed) {
        tinyusb_cdcacm_register_callback(itf, CDC_EVENT_LINE_STATE_CHANGED, cfg->callback_line_state_changed);
    }
    if (cfg->callback_line_coding_changed) {
        tinyusb_cdcacm_register_callback( itf, CDC_EVENT_LINE_CODING_CHANGED, cfg->callback_line_coding_changed);
    }
 
    /* Buffers */
    esp_tusb_cdcacm_t *acm = get_acm(itf);
 
    acm->ringbuf_read_mux = xSemaphoreCreateMutex();
    ESP_GOTO_ON_FALSE(acm->ringbuf_read_mux, ESP_ERR_NO_MEM, out3, TAG, "Creation of a ringbuf mutex failed");
 
    acm->rx_tfbuf = malloc(CONFIG_TINYUSB_CDC_RX_BUFSIZE);
    ESP_GOTO_ON_FALSE(acm->rx_tfbuf, ESP_ERR_NO_MEM, out2, TAG, "Creation buffer error");
 
    acm->rx_unread_buf_sz = cfg->rx_unread_buf_sz == 0 ? RX_UNREADBUF_SZ_DEFAULT : cfg->rx_unread_buf_sz;
    acm->rx_unread_buf = xRingbufferCreate(acm->rx_unread_buf_sz, RINGBUF_TYPE_BYTEBUF);
    ESP_GOTO_ON_FALSE(acm->rx_unread_buf, ESP_ERR_NO_MEM, out1, TAG, "Creation buffer error");
 
    ESP_LOGD(TAG, "Comm Initialized buff:%d bytes", cfg->rx_unread_buf_sz);
    return ESP_OK;
 
out1:
    free(acm->rx_tfbuf);
out2:
    vSemaphoreDelete(acm->ringbuf_read_mux);
out3:
    free_obj(itf);
out4:
    tinyusb_cdc_deinit(itf);
    return ret;
}

References alloc_obj(), tinyusb_config_cdcacm_t::callback_line_coding_changed, tinyusb_config_cdcacm_t::callback_line_state_changed, tinyusb_config_cdcacm_t::callback_rx, tinyusb_config_cdcacm_t::callback_rx_wanted_char, CDC_EVENT_LINE_CODING_CHANGED, CDC_EVENT_LINE_STATE_CHANGED, CDC_EVENT_RX, CDC_EVENT_RX_WANTED_CHAR, tinyusb_config_cdcacm_t::cdc_port, ESP_LOGD, ESP_OK, ESP_RETURN_ON_ERROR, free_obj(), get_acm(), esp_tusb_cdcacm_t::ringbuf_read_mux, esp_tusb_cdcacm_t::rx_tfbuf, esp_tusb_cdcacm_t::rx_unread_buf, esp_tusb_cdcacm_t::rx_unread_buf_sz, tinyusb_config_cdcacm_t::rx_unread_buf_sz, RX_UNREADBUF_SZ_DEFAULT, TAG, tinyusb_cdc_deinit(), tinyusb_cdc_init(), tinyusb_cdcacm_register_callback(), and tinyusb_config_cdcacm_t::usb_dev.

Referenced by app_main().

Here is the call graph for this function:

Here is the caller graph for this function:

tusb_cdc_acm_initialized()

bool tusb_cdc_acm_initialized

(

tinyusb_cdcacm_itf_t

itf

)

Check if the ACM initialized.

Parameters

itf	- number of a CDC object

Returns

true or false

Definition at line 407 of file tusb_cdc_acm.c.

{
    esp_tusb_cdcacm_t *acm = get_acm(itf);
    if (acm) {
        return true;
    } else {
        return false;
    }
}

References get_acm().

Referenced by cdc_tx_task(), and esp_vfs_tusb_cdc_register().

Here is the call graph for this function:

Here is the caller graph for this function: