diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 015558a..aa48a26 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -4,3 +4,19 @@ repos: hooks: - id: astyle_py args: ['--style=otbs', '--attach-namespaces', '--attach-classes', '--indent=spaces=4', '--convert-tabs', '--align-pointer=name', '--align-reference=name', '--keep-one-line-statements', '--pad-header', '--pad-oper'] + +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.3.0 + hooks: + - id: trailing-whitespace + files: ^usb/ + types_or: [c, c++] + - id: end-of-file-fixer + files: ^usb/ + types_or: [c, c++] + - id: check-merge-conflict + - id: mixed-line-ending + files: ^usb/ # temporary USB only + types_or: [c, c++] + args: ['--fix=lf'] + description: Forces to replace line ending by the UNIX 'lf' character diff --git a/usb/usb_host_cdc_acm/include/usb/cdc_acm_host.h b/usb/usb_host_cdc_acm/include/usb/cdc_acm_host.h index 0489132..90f5a20 100644 --- a/usb/usb_host_cdc_acm/include/usb/cdc_acm_host.h +++ b/usb/usb_host_cdc_acm/include/usb/cdc_acm_host.h @@ -1,342 +1,342 @@ -/* - * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD - * - * SPDX-License-Identifier: Apache-2.0 - */ - -#pragma once - -#include -#include "usb/usb_host.h" -#include "usb_types_cdc.h" -#include "esp_err.h" - -#ifdef __cplusplus -extern "C" { -#endif - -typedef struct cdc_dev_s *cdc_acm_dev_hdl_t; - -/** - * @brief Line Coding structure - * @see Table 17, USB CDC-PSTN specification rev. 1.2 - */ -typedef struct { - uint32_t dwDTERate; // in bits per second - uint8_t bCharFormat; // 0: 1 stopbit, 1: 1.5 stopbits, 2: 2 stopbits - uint8_t bParityType; // 0: None, 1: Odd, 2: Even, 3: Mark, 4: Space - uint8_t bDataBits; // 5, 6, 7, 8 or 16 -} __attribute__((packed)) cdc_acm_line_coding_t; - -/** - * @brief UART State Bitmap - * @see Table 31, USB CDC-PSTN specification rev. 1.2 - */ -typedef union { - struct { - uint16_t bRxCarrier : 1; // State of receiver carrier detection mechanism of device. This signal corresponds to V.24 signal 109 and RS-232 signal DCD. - uint16_t bTxCarrier : 1; // State of transmission carrier. This signal corresponds to V.24 signal 106 and RS-232 signal DSR. - uint16_t bBreak : 1; // State of break detection mechanism of the device. - uint16_t bRingSignal : 1; // State of ring signal detection of the device. - uint16_t bFraming : 1; // A framing error has occurred. - uint16_t bParity : 1; // A parity error has occurred. - uint16_t bOverRun : 1; // Received data has been discarded due to overrun in the device. - uint16_t reserved : 9; - }; - uint16_t val; -} cdc_acm_uart_state_t; - -/** - * @brief CDC-ACM Device Event types to upper layer - * - */ -typedef enum { - CDC_ACM_HOST_ERROR, - CDC_ACM_HOST_SERIAL_STATE, - CDC_ACM_HOST_NETWORK_CONNECTION, - CDC_ACM_HOST_DEVICE_DISCONNECTED -} cdc_acm_host_dev_event_t; - -/** - * @brief CDC-ACM Device Event data structure - * - */ -typedef struct { - cdc_acm_host_dev_event_t type; - union { - int error; //!< Error code from USB Host - cdc_acm_uart_state_t serial_state; //!< Serial (UART) state - bool network_connected; //!< Network connection event - cdc_acm_dev_hdl_t cdc_hdl; //!< Disconnection event - } data; -} cdc_acm_host_dev_event_data_t; - -/** - * @brief New USB device callback - * - * Provides already opened usb_dev, that will be closed after this callback returns. - * This is useful for peeking device's descriptors, e.g. peeking VID/PID and loading proper driver. - * - * @attention This callback is called from USB Host context, so the CDC device can't be opened here. - */ -typedef void (*cdc_acm_new_dev_callback_t)(usb_device_handle_t usb_dev); - -/** - * @brief Data receive callback type - */ -typedef void (*cdc_acm_data_callback_t)(uint8_t *data, size_t data_len, void *user_arg); - -/** - * @brief Device event callback type - * @see cdc_acm_host_dev_event_data_t - */ -typedef void (*cdc_acm_host_dev_callback_t)(const cdc_acm_host_dev_event_data_t *event, void *user_ctx); - -/** - * @brief Configuration structure of USB Host CDC-ACM driver - * - */ -typedef struct { - size_t driver_task_stack_size; /**< Stack size of the driver's task */ - unsigned driver_task_priority; /**< Priority of the driver's task */ - int xCoreID; /**< Core affinity of the driver's task */ - cdc_acm_new_dev_callback_t new_dev_cb; /**< New USB device connected callback. Can be NULL. */ -} cdc_acm_host_driver_config_t; - -/** - * @brief Configuration structure of CDC-ACM device - * - */ -typedef struct { - uint32_t connection_timeout_ms; /**< Timeout for USB device connection in [ms] */ - size_t out_buffer_size; /**< Maximum size of USB bulk out transfer, set to 0 for read-only devices */ - cdc_acm_host_dev_callback_t event_cb; /**< Device's event callback function. Can be NULL */ - cdc_acm_data_callback_t data_cb; /**< Device's data RX callback function. Can be NULL for write-only devices */ - void *user_arg; /**< User's argument that will be passed to the callbacks */ -} cdc_acm_host_device_config_t; - -/** - * @brief Install CDC-ACM driver - * - * - USB Host Library must already be installed before calling this function (via usb_host_install()) - * - This function should be called before calling any other CDC driver functions - * - * @param[in] driver_config Driver configuration structure. If set to NULL, a default configuration will be used. - * @return esp_err_t - */ -esp_err_t cdc_acm_host_install(const cdc_acm_host_driver_config_t *driver_config); - -/** - * @brief Uninstall CDC-ACM driver - * - * - Users must ensure that all CDC devices must be closed via cdc_acm_host_close() before calling this function - * - * @return esp_err_t - */ -esp_err_t cdc_acm_host_uninstall(void); - -/** - * @brief Open CDC-ACM compliant device - * - * CDC-ACM compliant device must contain either an Interface Association Descriptor or CDC-Union descriptor, - * which are used for the driver's configuration. - * - * @param[in] vid Device's Vendor ID - * @param[in] pid Device's Product ID - * @param[in] interface_idx Index of device's interface used for CDC-ACM communication - * @param[in] dev_config Configuration structure of the device - * @param[out] cdc_hdl_ret CDC device handle - * @return esp_err_t - */ -esp_err_t cdc_acm_host_open(uint16_t vid, uint16_t pid, uint8_t interface_idx, const cdc_acm_host_device_config_t *dev_config, cdc_acm_dev_hdl_t *cdc_hdl_ret); - -/** - * @brief Open CDC-ACM non-compliant device - * - * CDC-ACM non-compliant device acts as CDC-ACM device but doesn't support all its features. - * User must provide the interface index that will be used (zero for non-composite devices). - * - * @param[in] vid Device's Vendor ID - * @param[in] pid Device's Product ID - * @param[in] interface_idx Index of device's interface used for CDC-ACM like communication - * @param[in] dev_config Configuration structure of the device - * @param[out] cdc_hdl_ret CDC device handle - * @return esp_err_t - */ -esp_err_t cdc_acm_host_open_vendor_specific(uint16_t vid, uint16_t pid, uint8_t interface_num, const cdc_acm_host_device_config_t *dev_config, cdc_acm_dev_hdl_t *cdc_hdl_ret); - -/** - * @brief Close CDC device and release its resources - * - * @note All in-flight transfers will be prematurely canceled. - * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() - * @return esp_err_t - */ -esp_err_t cdc_acm_host_close(cdc_acm_dev_hdl_t cdc_hdl); - -/** - * @brief Transmit data - blocking mode - * - * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() - * @param[in] data Data to be sent - * @param[in] data_len Data length - * @param[in] timeout_ms Timeout in [ms] - * @return esp_err_t - */ -esp_err_t cdc_acm_host_data_tx_blocking(cdc_acm_dev_hdl_t cdc_hdl, const uint8_t *data, size_t data_len, uint32_t timeout_ms); - -/** - * @brief SetLineCoding function - * - * @see Chapter 6.3.10, USB CDC-PSTN specification rev. 1.2 - * - * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() - * @param[in] line_coding Line Coding structure - * @return esp_err_t - */ -esp_err_t cdc_acm_host_line_coding_set(cdc_acm_dev_hdl_t cdc_hdl, const cdc_acm_line_coding_t *line_coding); - -/** - * @brief GetLineCoding function - * - * @see Chapter 6.3.11, USB CDC-PSTN specification rev. 1.2 - * - * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() - * @param[out] line_coding Line Coding structure to be filled - * @return esp_err_t - */ -esp_err_t cdc_acm_host_line_coding_get(cdc_acm_dev_hdl_t cdc_hdl, cdc_acm_line_coding_t *line_coding); - -/** - * @brief SetControlLineState function - * - * @see Chapter 6.3.12, USB CDC-PSTN specification rev. 1.2 - * - * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() - * @param[in] dtr Indicates to DCE if DTE is present or not. This signal corresponds to V.24 signal 108/2 and RS-232 signal Data Terminal Ready. - * @param[in] rts Carrier control for half duplex modems. This signal corresponds to V.24 signal 105 and RS-232 signal Request To Send. - * @return esp_err_t - */ -esp_err_t cdc_acm_host_set_control_line_state(cdc_acm_dev_hdl_t cdc_hdl, bool dtr, bool rts); - -/** - * @brief SendBreak function - * - * This function will block until the duration_ms has passed. - * - * @see Chapter 6.3.13, USB CDC-PSTN specification rev. 1.2 - * - * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() - * @param[in] duration_ms Duration of the Break signal in [ms] - * @return esp_err_t - */ -esp_err_t cdc_acm_host_send_break(cdc_acm_dev_hdl_t cdc_hdl, uint16_t duration_ms); - -/** - * @brief Print device's descriptors - * - * Device and full Configuration descriptors are printed in human readable format to stdout. - * - * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() - */ -void cdc_acm_host_desc_print(cdc_acm_dev_hdl_t cdc_hdl); - -/** - * @brief Get protocols defined in USB-CDC interface descriptors - * - * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() - * @param[out] comm Communication protocol - * @param[out] data Data protocol - * @return esp_err_t - */ -esp_err_t cdc_acm_host_protocols_get(cdc_acm_dev_hdl_t cdc_hdl, cdc_comm_protocol_t *comm, cdc_data_protocol_t *data); - -/** - * @brief Send command to CTRL endpoint - * - * Sends Control transfer as described in USB specification chapter 9. - * This function can be used by device drivers that use custom/vendor specific commands. - * These commands can either extend or replace commands defined in USB CDC-PSTN specification rev. 1.2. - * - * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() - * @param[in] bmRequestType Field of USB control request - * @param[in] bRequest Field of USB control request - * @param[in] wValue Field of USB control request - * @param[in] wIndex Field of USB control request - * @param[in] wLength Field of USB control request - * @param[inout] data Field of USB control request - * @return esp_err_t - */ -esp_err_t cdc_acm_host_send_custom_request(cdc_acm_dev_hdl_t cdc_hdl, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, uint16_t wLength, uint8_t *data); - -#ifdef __cplusplus -} -class CdcAcmDevice { -public: - // Operators - CdcAcmDevice() : cdc_hdl(NULL) {}; - ~CdcAcmDevice() - { - // Close CDC-ACM device, if it wasn't explicitly closed - if (this->cdc_hdl != NULL) { - this->close(); - } - } - - inline esp_err_t tx_blocking(uint8_t *data, size_t len, uint32_t timeout_ms = 100) - { - return cdc_acm_host_data_tx_blocking(this->cdc_hdl, data, len, timeout_ms); - } - - inline esp_err_t open(uint16_t vid, uint16_t pid, uint8_t interface_idx, const cdc_acm_host_device_config_t *dev_config) - { - return cdc_acm_host_open(vid, pid, interface_idx, dev_config, &this->cdc_hdl); - } - - inline esp_err_t open_vendor_specific(uint16_t vid, uint16_t pid, uint8_t interface_idx, const cdc_acm_host_device_config_t *dev_config) - { - return cdc_acm_host_open_vendor_specific(vid, pid, interface_idx, dev_config, &this->cdc_hdl); - } - - inline esp_err_t close() - { - esp_err_t err = cdc_acm_host_close(this->cdc_hdl); - if (err == ESP_OK) { - this->cdc_hdl = NULL; - } - return err; - } - - inline esp_err_t line_coding_get(cdc_acm_line_coding_t *line_coding) - { - return cdc_acm_host_line_coding_get(this->cdc_hdl, line_coding); - } - - inline esp_err_t line_coding_set(cdc_acm_line_coding_t *line_coding) - { - return cdc_acm_host_line_coding_set(this->cdc_hdl, line_coding); - } - - inline esp_err_t set_control_line_state(bool dtr, bool rts) - { - return cdc_acm_host_set_control_line_state(this->cdc_hdl, dtr, rts); - } - - inline esp_err_t send_break(uint16_t duration_ms) - { - return cdc_acm_host_send_break(this->cdc_hdl, duration_ms); - } - - inline esp_err_t send_custom_request(uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, uint16_t wLength, uint8_t *data) - { - return cdc_acm_host_send_custom_request(this->cdc_hdl, bmRequestType, bRequest, wValue, wIndex, wLength, data); - } - -private: - CdcAcmDevice(const CdcAcmDevice &Copy); - CdcAcmDevice &operator= (const CdcAcmDevice &Copy); - bool operator== (const CdcAcmDevice ¶m) const; - bool operator!= (const CdcAcmDevice ¶m) const; - cdc_acm_dev_hdl_t cdc_hdl; -}; -#endif +/* + * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#pragma once + +#include +#include "usb/usb_host.h" +#include "usb_types_cdc.h" +#include "esp_err.h" + +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct cdc_dev_s *cdc_acm_dev_hdl_t; + +/** + * @brief Line Coding structure + * @see Table 17, USB CDC-PSTN specification rev. 1.2 + */ +typedef struct { + uint32_t dwDTERate; // in bits per second + uint8_t bCharFormat; // 0: 1 stopbit, 1: 1.5 stopbits, 2: 2 stopbits + uint8_t bParityType; // 0: None, 1: Odd, 2: Even, 3: Mark, 4: Space + uint8_t bDataBits; // 5, 6, 7, 8 or 16 +} __attribute__((packed)) cdc_acm_line_coding_t; + +/** + * @brief UART State Bitmap + * @see Table 31, USB CDC-PSTN specification rev. 1.2 + */ +typedef union { + struct { + uint16_t bRxCarrier : 1; // State of receiver carrier detection mechanism of device. This signal corresponds to V.24 signal 109 and RS-232 signal DCD. + uint16_t bTxCarrier : 1; // State of transmission carrier. This signal corresponds to V.24 signal 106 and RS-232 signal DSR. + uint16_t bBreak : 1; // State of break detection mechanism of the device. + uint16_t bRingSignal : 1; // State of ring signal detection of the device. + uint16_t bFraming : 1; // A framing error has occurred. + uint16_t bParity : 1; // A parity error has occurred. + uint16_t bOverRun : 1; // Received data has been discarded due to overrun in the device. + uint16_t reserved : 9; + }; + uint16_t val; +} cdc_acm_uart_state_t; + +/** + * @brief CDC-ACM Device Event types to upper layer + * + */ +typedef enum { + CDC_ACM_HOST_ERROR, + CDC_ACM_HOST_SERIAL_STATE, + CDC_ACM_HOST_NETWORK_CONNECTION, + CDC_ACM_HOST_DEVICE_DISCONNECTED +} cdc_acm_host_dev_event_t; + +/** + * @brief CDC-ACM Device Event data structure + * + */ +typedef struct { + cdc_acm_host_dev_event_t type; + union { + int error; //!< Error code from USB Host + cdc_acm_uart_state_t serial_state; //!< Serial (UART) state + bool network_connected; //!< Network connection event + cdc_acm_dev_hdl_t cdc_hdl; //!< Disconnection event + } data; +} cdc_acm_host_dev_event_data_t; + +/** + * @brief New USB device callback + * + * Provides already opened usb_dev, that will be closed after this callback returns. + * This is useful for peeking device's descriptors, e.g. peeking VID/PID and loading proper driver. + * + * @attention This callback is called from USB Host context, so the CDC device can't be opened here. + */ +typedef void (*cdc_acm_new_dev_callback_t)(usb_device_handle_t usb_dev); + +/** + * @brief Data receive callback type + */ +typedef void (*cdc_acm_data_callback_t)(uint8_t *data, size_t data_len, void *user_arg); + +/** + * @brief Device event callback type + * @see cdc_acm_host_dev_event_data_t + */ +typedef void (*cdc_acm_host_dev_callback_t)(const cdc_acm_host_dev_event_data_t *event, void *user_ctx); + +/** + * @brief Configuration structure of USB Host CDC-ACM driver + * + */ +typedef struct { + size_t driver_task_stack_size; /**< Stack size of the driver's task */ + unsigned driver_task_priority; /**< Priority of the driver's task */ + int xCoreID; /**< Core affinity of the driver's task */ + cdc_acm_new_dev_callback_t new_dev_cb; /**< New USB device connected callback. Can be NULL. */ +} cdc_acm_host_driver_config_t; + +/** + * @brief Configuration structure of CDC-ACM device + * + */ +typedef struct { + uint32_t connection_timeout_ms; /**< Timeout for USB device connection in [ms] */ + size_t out_buffer_size; /**< Maximum size of USB bulk out transfer, set to 0 for read-only devices */ + cdc_acm_host_dev_callback_t event_cb; /**< Device's event callback function. Can be NULL */ + cdc_acm_data_callback_t data_cb; /**< Device's data RX callback function. Can be NULL for write-only devices */ + void *user_arg; /**< User's argument that will be passed to the callbacks */ +} cdc_acm_host_device_config_t; + +/** + * @brief Install CDC-ACM driver + * + * - USB Host Library must already be installed before calling this function (via usb_host_install()) + * - This function should be called before calling any other CDC driver functions + * + * @param[in] driver_config Driver configuration structure. If set to NULL, a default configuration will be used. + * @return esp_err_t + */ +esp_err_t cdc_acm_host_install(const cdc_acm_host_driver_config_t *driver_config); + +/** + * @brief Uninstall CDC-ACM driver + * + * - Users must ensure that all CDC devices must be closed via cdc_acm_host_close() before calling this function + * + * @return esp_err_t + */ +esp_err_t cdc_acm_host_uninstall(void); + +/** + * @brief Open CDC-ACM compliant device + * + * CDC-ACM compliant device must contain either an Interface Association Descriptor or CDC-Union descriptor, + * which are used for the driver's configuration. + * + * @param[in] vid Device's Vendor ID + * @param[in] pid Device's Product ID + * @param[in] interface_idx Index of device's interface used for CDC-ACM communication + * @param[in] dev_config Configuration structure of the device + * @param[out] cdc_hdl_ret CDC device handle + * @return esp_err_t + */ +esp_err_t cdc_acm_host_open(uint16_t vid, uint16_t pid, uint8_t interface_idx, const cdc_acm_host_device_config_t *dev_config, cdc_acm_dev_hdl_t *cdc_hdl_ret); + +/** + * @brief Open CDC-ACM non-compliant device + * + * CDC-ACM non-compliant device acts as CDC-ACM device but doesn't support all its features. + * User must provide the interface index that will be used (zero for non-composite devices). + * + * @param[in] vid Device's Vendor ID + * @param[in] pid Device's Product ID + * @param[in] interface_idx Index of device's interface used for CDC-ACM like communication + * @param[in] dev_config Configuration structure of the device + * @param[out] cdc_hdl_ret CDC device handle + * @return esp_err_t + */ +esp_err_t cdc_acm_host_open_vendor_specific(uint16_t vid, uint16_t pid, uint8_t interface_num, const cdc_acm_host_device_config_t *dev_config, cdc_acm_dev_hdl_t *cdc_hdl_ret); + +/** + * @brief Close CDC device and release its resources + * + * @note All in-flight transfers will be prematurely canceled. + * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() + * @return esp_err_t + */ +esp_err_t cdc_acm_host_close(cdc_acm_dev_hdl_t cdc_hdl); + +/** + * @brief Transmit data - blocking mode + * + * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() + * @param[in] data Data to be sent + * @param[in] data_len Data length + * @param[in] timeout_ms Timeout in [ms] + * @return esp_err_t + */ +esp_err_t cdc_acm_host_data_tx_blocking(cdc_acm_dev_hdl_t cdc_hdl, const uint8_t *data, size_t data_len, uint32_t timeout_ms); + +/** + * @brief SetLineCoding function + * + * @see Chapter 6.3.10, USB CDC-PSTN specification rev. 1.2 + * + * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() + * @param[in] line_coding Line Coding structure + * @return esp_err_t + */ +esp_err_t cdc_acm_host_line_coding_set(cdc_acm_dev_hdl_t cdc_hdl, const cdc_acm_line_coding_t *line_coding); + +/** + * @brief GetLineCoding function + * + * @see Chapter 6.3.11, USB CDC-PSTN specification rev. 1.2 + * + * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() + * @param[out] line_coding Line Coding structure to be filled + * @return esp_err_t + */ +esp_err_t cdc_acm_host_line_coding_get(cdc_acm_dev_hdl_t cdc_hdl, cdc_acm_line_coding_t *line_coding); + +/** + * @brief SetControlLineState function + * + * @see Chapter 6.3.12, USB CDC-PSTN specification rev. 1.2 + * + * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() + * @param[in] dtr Indicates to DCE if DTE is present or not. This signal corresponds to V.24 signal 108/2 and RS-232 signal Data Terminal Ready. + * @param[in] rts Carrier control for half duplex modems. This signal corresponds to V.24 signal 105 and RS-232 signal Request To Send. + * @return esp_err_t + */ +esp_err_t cdc_acm_host_set_control_line_state(cdc_acm_dev_hdl_t cdc_hdl, bool dtr, bool rts); + +/** + * @brief SendBreak function + * + * This function will block until the duration_ms has passed. + * + * @see Chapter 6.3.13, USB CDC-PSTN specification rev. 1.2 + * + * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() + * @param[in] duration_ms Duration of the Break signal in [ms] + * @return esp_err_t + */ +esp_err_t cdc_acm_host_send_break(cdc_acm_dev_hdl_t cdc_hdl, uint16_t duration_ms); + +/** + * @brief Print device's descriptors + * + * Device and full Configuration descriptors are printed in human readable format to stdout. + * + * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() + */ +void cdc_acm_host_desc_print(cdc_acm_dev_hdl_t cdc_hdl); + +/** + * @brief Get protocols defined in USB-CDC interface descriptors + * + * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() + * @param[out] comm Communication protocol + * @param[out] data Data protocol + * @return esp_err_t + */ +esp_err_t cdc_acm_host_protocols_get(cdc_acm_dev_hdl_t cdc_hdl, cdc_comm_protocol_t *comm, cdc_data_protocol_t *data); + +/** + * @brief Send command to CTRL endpoint + * + * Sends Control transfer as described in USB specification chapter 9. + * This function can be used by device drivers that use custom/vendor specific commands. + * These commands can either extend or replace commands defined in USB CDC-PSTN specification rev. 1.2. + * + * @param cdc_hdl CDC handle obtained from cdc_acm_host_open() + * @param[in] bmRequestType Field of USB control request + * @param[in] bRequest Field of USB control request + * @param[in] wValue Field of USB control request + * @param[in] wIndex Field of USB control request + * @param[in] wLength Field of USB control request + * @param[inout] data Field of USB control request + * @return esp_err_t + */ +esp_err_t cdc_acm_host_send_custom_request(cdc_acm_dev_hdl_t cdc_hdl, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, uint16_t wLength, uint8_t *data); + +#ifdef __cplusplus +} +class CdcAcmDevice { +public: + // Operators + CdcAcmDevice() : cdc_hdl(NULL) {}; + ~CdcAcmDevice() + { + // Close CDC-ACM device, if it wasn't explicitly closed + if (this->cdc_hdl != NULL) { + this->close(); + } + } + + inline esp_err_t tx_blocking(uint8_t *data, size_t len, uint32_t timeout_ms = 100) + { + return cdc_acm_host_data_tx_blocking(this->cdc_hdl, data, len, timeout_ms); + } + + inline esp_err_t open(uint16_t vid, uint16_t pid, uint8_t interface_idx, const cdc_acm_host_device_config_t *dev_config) + { + return cdc_acm_host_open(vid, pid, interface_idx, dev_config, &this->cdc_hdl); + } + + inline esp_err_t open_vendor_specific(uint16_t vid, uint16_t pid, uint8_t interface_idx, const cdc_acm_host_device_config_t *dev_config) + { + return cdc_acm_host_open_vendor_specific(vid, pid, interface_idx, dev_config, &this->cdc_hdl); + } + + inline esp_err_t close() + { + esp_err_t err = cdc_acm_host_close(this->cdc_hdl); + if (err == ESP_OK) { + this->cdc_hdl = NULL; + } + return err; + } + + inline esp_err_t line_coding_get(cdc_acm_line_coding_t *line_coding) + { + return cdc_acm_host_line_coding_get(this->cdc_hdl, line_coding); + } + + inline esp_err_t line_coding_set(cdc_acm_line_coding_t *line_coding) + { + return cdc_acm_host_line_coding_set(this->cdc_hdl, line_coding); + } + + inline esp_err_t set_control_line_state(bool dtr, bool rts) + { + return cdc_acm_host_set_control_line_state(this->cdc_hdl, dtr, rts); + } + + inline esp_err_t send_break(uint16_t duration_ms) + { + return cdc_acm_host_send_break(this->cdc_hdl, duration_ms); + } + + inline esp_err_t send_custom_request(uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, uint16_t wLength, uint8_t *data) + { + return cdc_acm_host_send_custom_request(this->cdc_hdl, bmRequestType, bRequest, wValue, wIndex, wLength, data); + } + +private: + CdcAcmDevice(const CdcAcmDevice &Copy); + CdcAcmDevice &operator= (const CdcAcmDevice &Copy); + bool operator== (const CdcAcmDevice ¶m) const; + bool operator!= (const CdcAcmDevice ¶m) const; + cdc_acm_dev_hdl_t cdc_hdl; +}; +#endif diff --git a/usb/usb_host_cdc_acm/test/test_cdc_acm_host.c b/usb/usb_host_cdc_acm/test/test_cdc_acm_host.c index bc173e5..91836c7 100644 --- a/usb/usb_host_cdc_acm/test/test_cdc_acm_host.c +++ b/usb/usb_host_cdc_acm/test/test_cdc_acm_host.c @@ -1,448 +1,448 @@ -/* - * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD - * - * SPDX-License-Identifier: CC0-1.0 - */ - -#include "soc/soc_caps.h" -#if SOC_USB_OTG_SUPPORTED - -#include -#include "esp_system.h" -#include "freertos/FreeRTOS.h" -#include "freertos/task.h" -#include "esp_log.h" -#include "esp_err.h" - -#include "esp_private/usb_phy.h" -#include "usb/usb_host.h" -#include "usb/cdc_acm_host.h" -#include - -#include "esp_intr_alloc.h" - -#include "unity.h" -#include "soc/usb_wrap_struct.h" - -static uint8_t tx_buf[] = "HELLO"; -static uint8_t tx_buf2[] = "WORLD"; -static int nb_of_responses; -static int nb_of_responses2; -static usb_phy_handle_t phy_hdl = NULL; - -static void force_conn_state(bool connected, TickType_t delay_ticks) -{ - TEST_ASSERT_NOT_EQUAL(NULL, phy_hdl); - if (delay_ticks > 0) { - //Delay of 0 ticks causes a yield. So skip if delay_ticks is 0. - vTaskDelay(delay_ticks); - } - ESP_ERROR_CHECK(usb_phy_action(phy_hdl, (connected) ? USB_PHY_ACTION_HOST_ALLOW_CONN : USB_PHY_ACTION_HOST_FORCE_DISCONN)); -} - -void usb_lib_task(void *arg) -{ - // Initialize the internal USB PHY to connect to the USB OTG peripheral. We manually install the USB PHY for testing - usb_phy_config_t phy_config = { - .controller = USB_PHY_CTRL_OTG, - .target = USB_PHY_TARGET_INT, - .otg_mode = USB_OTG_MODE_HOST, - .otg_speed = USB_PHY_SPEED_UNDEFINED, //In Host mode, the speed is determined by the connected device - .gpio_conf = NULL, - }; - TEST_ASSERT_EQUAL(ESP_OK, usb_new_phy(&phy_config, &phy_hdl)); - // Install USB Host driver. Should only be called once in entire application - const usb_host_config_t host_config = { - .skip_phy_setup = true, - .intr_flags = ESP_INTR_FLAG_LEVEL1, - }; - TEST_ASSERT_EQUAL(ESP_OK, usb_host_install(&host_config)); - printf("USB Host installed\n"); - xTaskNotifyGive(arg); - - bool all_clients_gone = false; - bool all_dev_free = false; - while (!all_clients_gone || !all_dev_free) { - // Start handling system events - uint32_t event_flags; - usb_host_lib_handle_events(portMAX_DELAY, &event_flags); - if (event_flags & USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS) { - printf("No more clients\n"); - usb_host_device_free_all(); - all_clients_gone = true; - } - if (event_flags & USB_HOST_LIB_EVENT_FLAGS_ALL_FREE) { - printf("All devices freed\n"); - all_dev_free = true; - } - } - - // Clean up USB Host - vTaskDelay(10); // Short delay to allow clients clean-up - TEST_ASSERT_EQUAL(ESP_OK, usb_host_uninstall()); - TEST_ASSERT_EQUAL(ESP_OK, usb_del_phy(phy_hdl)); //Tear down USB PHY - phy_hdl = NULL; - vTaskDelete(NULL); -} - -void test_install_cdc_driver(void) -{ - // Create a task that will handle USB library events - TEST_ASSERT_EQUAL(pdTRUE, xTaskCreatePinnedToCore(usb_lib_task, "usb_lib", 4 * 4096, xTaskGetCurrentTaskHandle(), 10, NULL, 0)); - ulTaskNotifyTake(false, 1000); - - printf("Installing CDC-ACM driver\n"); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_install(NULL)); -} - -/* ------------------------------- Callbacks -------------------------------- */ -static void handle_rx(uint8_t *data, size_t data_len, void *arg) -{ - printf("Data received\n"); - nb_of_responses++; - TEST_ASSERT_EQUAL_STRING_LEN(data, arg, data_len); -} - -static void handle_rx2(uint8_t *data, size_t data_len, void *arg) -{ - printf("Data received 2\n"); - nb_of_responses2++; - TEST_ASSERT_EQUAL_STRING_LEN(data, arg, data_len); -} - -static void notif_cb(const cdc_acm_host_dev_event_data_t *event, void *user_ctx) -{ - switch (event->type) { - case CDC_ACM_HOST_ERROR: - printf("Error event %d\n", event->data.error); - break; - case CDC_ACM_HOST_SERIAL_STATE: - break; - case CDC_ACM_HOST_NETWORK_CONNECTION: - break; - case CDC_ACM_HOST_DEVICE_DISCONNECTED: - printf("Disconnection event\n"); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(event->data.cdc_hdl)); - xTaskNotifyGive(user_ctx); - break; - default: - assert(false); - } -} - -static bool new_dev_cb_called = false; -static void new_dev_cb(usb_device_handle_t usb_dev) -{ - new_dev_cb_called = true; - const usb_config_desc_t *config_desc; - const usb_device_desc_t *device_desc; - - // Get descriptors - TEST_ASSERT_EQUAL(ESP_OK, usb_host_get_device_descriptor(usb_dev, &device_desc)); - TEST_ASSERT_EQUAL(ESP_OK, usb_host_get_active_config_descriptor(usb_dev, &config_desc)); - - printf("New device connected. VID = 0x%04X PID = %04X\n", device_desc->idVendor, device_desc->idProduct); -} - -/* Basic test to check CDC communication: - * open/read/write/close device - * CDC-ACM specific commands: set/get_line_coding, set_control_line_state */ -TEST_CASE("read_write", "[cdc_acm]") -{ - nb_of_responses = 0; - cdc_acm_dev_hdl_t cdc_dev = NULL; - - test_install_cdc_driver(); - - const cdc_acm_host_device_config_t dev_config = { - .connection_timeout_ms = 500, - .out_buffer_size = 64, - .event_cb = notif_cb, - .data_cb = handle_rx, - .user_arg = tx_buf, - }; - - printf("Opening CDC-ACM device\n"); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); // 0x303A:0x4002 (TinyUSB Dual CDC device) - TEST_ASSERT_NOT_NULL(cdc_dev); - cdc_acm_host_desc_print(cdc_dev); - vTaskDelay(100); - - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_data_tx_blocking(cdc_dev, tx_buf, sizeof(tx_buf), 1000)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_data_tx_blocking(cdc_dev, tx_buf, sizeof(tx_buf), 1000)); - vTaskDelay(100); // Wait until responses are processed - - // We sent two messages, should get two responses - TEST_ASSERT_EQUAL(2, nb_of_responses); - - cdc_acm_line_coding_t line_coding_get; - const cdc_acm_line_coding_t line_coding_set = { - .dwDTERate = 9600, - .bDataBits = 7, - .bParityType = 1, - .bCharFormat = 1, - }; - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_line_coding_set(cdc_dev, &line_coding_set)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_line_coding_get(cdc_dev, &line_coding_get)); - TEST_ASSERT_EQUAL_MEMORY(&line_coding_set, &line_coding_get, sizeof(cdc_acm_line_coding_t)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_set_control_line_state(cdc_dev, true, false)); - - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); - - vTaskDelay(20); //Short delay to allow task to be cleaned up -} - -/* Test communication with multiple CDC-ACM devices from one thread */ -TEST_CASE("multiple_devices", "[cdc_acm]") -{ - nb_of_responses = 0; - nb_of_responses2 = 0; - - test_install_cdc_driver(); - - printf("Opening 2 CDC-ACM devices\n"); - cdc_acm_dev_hdl_t cdc_dev1, cdc_dev2; - cdc_acm_host_device_config_t dev_config = { - .connection_timeout_ms = 1000, - .out_buffer_size = 64, - .event_cb = notif_cb, - .data_cb = handle_rx, - .user_arg = tx_buf, - }; - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev1)); // 0x303A:0x4002 (TinyUSB Dual CDC device) - dev_config.data_cb = handle_rx2; - dev_config.user_arg = tx_buf2; - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 2, &dev_config, &cdc_dev2)); // 0x303A:0x4002 (TinyUSB Dual CDC device) - TEST_ASSERT_NOT_NULL(cdc_dev1); - TEST_ASSERT_NOT_NULL(cdc_dev2); - - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_data_tx_blocking(cdc_dev1, tx_buf, sizeof(tx_buf), 1000)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_data_tx_blocking(cdc_dev2, tx_buf2, sizeof(tx_buf2), 1000)); - - vTaskDelay(100); // Wait for RX callbacks - - // We sent two messages, should get two responses - TEST_ASSERT_EQUAL(1, nb_of_responses); - TEST_ASSERT_EQUAL(1, nb_of_responses2); - - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev1)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev2)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); - - //Short delay to allow task to be cleaned up - vTaskDelay(20); -} - -#define MULTIPLE_THREADS_TRANSFERS_NUM 5 -#define MULTIPLE_THREADS_TASKS_NUM 4 -void tx_task(void *arg) -{ - cdc_acm_dev_hdl_t cdc_dev = (cdc_acm_dev_hdl_t) arg; - // Send multiple transfers to make sure that some of them will run at the same time - for (int i = 0; i < MULTIPLE_THREADS_TRANSFERS_NUM; i++) { - // BULK endpoints - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_data_tx_blocking(cdc_dev, tx_buf, sizeof(tx_buf), 1000)); - - // CTRL endpoints - cdc_acm_line_coding_t line_coding_get; - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_line_coding_get(cdc_dev, &line_coding_get)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_set_control_line_state(cdc_dev, true, false)); - } - vTaskDelete(NULL); -} - -/** - * @brief Multiple threads test - * - * In this test, one CDC device is accessed from multiple threads. - * It has to be opened/closed just once, though. - */ -TEST_CASE("multiple_threads", "[cdc_acm]") -{ - nb_of_responses = 0; - cdc_acm_dev_hdl_t cdc_dev; - test_install_cdc_driver(); - - const cdc_acm_host_device_config_t dev_config = { - .connection_timeout_ms = 5000, - .out_buffer_size = 64, - .event_cb = notif_cb, - .data_cb = handle_rx, - .user_arg = tx_buf, - }; - - printf("Opening CDC-ACM device\n"); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); // 0x303A:0x4002 (TinyUSB Dual CDC device) - TEST_ASSERT_NOT_NULL(cdc_dev); - - // Create two tasks that will try to access cdc_dev - for (int i = 0; i < MULTIPLE_THREADS_TASKS_NUM; i++) { - TEST_ASSERT_EQUAL(pdTRUE, xTaskCreate(tx_task, "CDC TX", 4096, cdc_dev, i + 3, NULL)); - } - - // Wait until all tasks finish - vTaskDelay(pdMS_TO_TICKS(500)); - TEST_ASSERT_EQUAL(MULTIPLE_THREADS_TASKS_NUM * MULTIPLE_THREADS_TRANSFERS_NUM, nb_of_responses); - - // Clean-up - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); - vTaskDelay(20); -} - -/* Test CDC driver reaction to USB device sudden disconnection */ -TEST_CASE("sudden_disconnection", "[cdc_acm]") -{ - test_install_cdc_driver(); - - cdc_acm_dev_hdl_t cdc_dev; - cdc_acm_host_device_config_t dev_config = { - .connection_timeout_ms = 1000, - .out_buffer_size = 64, - .event_cb = notif_cb, - .data_cb = handle_rx - }; - dev_config.user_arg = xTaskGetCurrentTaskHandle(); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); - TEST_ASSERT_NOT_NULL(cdc_dev); - - force_conn_state(false, pdMS_TO_TICKS(10)); // Simulate device disconnection - TEST_ASSERT_EQUAL(1, ulTaskNotifyTake(false, pdMS_TO_TICKS(100))); // Notify will succeed only if CDC_ACM_HOST_DEVICE_DISCONNECTED notification was generated - - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); - vTaskDelay(20); //Short delay to allow task to be cleaned up -} - -/** - * @brief CDC-ACM error handling test - * - * There are multiple erroneous scenarios checked in this test: - * - * -# Install CDC-ACM driver without USB Host - * -# Open device without installed driver - * -# Uninstall driver before installing it - * -# Open non-existent device - * -# Open the same device twice - * -# Uninstall driver with open devices - * -# Send data that is too large - * -# Send unsupported CDC request - * -# Write to read-only device - */ -TEST_CASE("error_handling", "[cdc_acm]") -{ - cdc_acm_dev_hdl_t cdc_dev; - cdc_acm_host_device_config_t dev_config = { - .connection_timeout_ms = 500, - .out_buffer_size = 64, - .event_cb = notif_cb, - .data_cb = handle_rx - }; - - // Install CDC-ACM driver without USB Host - TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, cdc_acm_host_install(NULL)); - - // Open device without installed driver - TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); - - // Uninstall driver before installing it - TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, cdc_acm_host_uninstall()); - - // Properly install USB and CDC drivers - test_install_cdc_driver(); - - // Open non-existent device - TEST_ASSERT_EQUAL(ESP_ERR_NOT_FOUND, cdc_acm_host_open(0x303A, 0x1234, 0, &dev_config, &cdc_dev)); // 0x303A:0x1234 this device is not connected to USB Host - TEST_ASSERT_NULL(cdc_dev); - - // Open regular device - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); - TEST_ASSERT_NOT_NULL(cdc_dev); - - // Open one CDC-ACM device twice - cdc_acm_dev_hdl_t cdc_dev_test; - TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev_test)); - TEST_ASSERT_NULL(cdc_dev_test); - - // Uninstall driver with open devices - TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, cdc_acm_host_uninstall()); - - // Send data that is too large and NULL data - TEST_ASSERT_EQUAL(ESP_ERR_INVALID_SIZE, cdc_acm_host_data_tx_blocking(cdc_dev, tx_buf, 1024, 1000)); - TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, cdc_acm_host_data_tx_blocking(cdc_dev, NULL, 10, 1000)); - - // Change mode to read-only and try to write to it - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev)); - dev_config.out_buffer_size = 0; // Read-only device - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); - TEST_ASSERT_NOT_NULL(cdc_dev); - TEST_ASSERT_EQUAL(ESP_ERR_NOT_SUPPORTED, cdc_acm_host_data_tx_blocking(cdc_dev, tx_buf, sizeof(tx_buf), 1000)); - - // Send unsupported CDC request (TinyUSB accepts SendBreak command, eventhough it doesn't support it) - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_send_break(cdc_dev, 100)); - - // Clean-up - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); - vTaskDelay(20); -} - -TEST_CASE("custom_command", "[cdc_acm]") -{ - test_install_cdc_driver(); - - // Open device with only CTRL endpoint (endpoint no 0) - cdc_acm_dev_hdl_t cdc_dev; - const cdc_acm_host_device_config_t dev_config = { - .connection_timeout_ms = 500, - .out_buffer_size = 0, - .event_cb = notif_cb, - .data_cb = NULL - }; - - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); - TEST_ASSERT_NOT_NULL(cdc_dev); - - // Corresponds to command: Set Control Line State, DTR on, RTS off - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_send_custom_request(cdc_dev, 0x21, 34, 1, 0, 0, NULL)); - - // Clean-up - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev)); - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); - vTaskDelay(20); -} - -TEST_CASE("new_device_connection", "[cdc_acm]") -{ - // Create a task that will handle USB library events - TEST_ASSERT_EQUAL(pdTRUE, xTaskCreatePinnedToCore(usb_lib_task, "usb_lib", 4 * 4096, xTaskGetCurrentTaskHandle(), 10, NULL, 0)); - ulTaskNotifyTake(false, 1000); - - printf("Installing CDC-ACM driver\n"); - const cdc_acm_host_driver_config_t driver_config = { - .driver_task_priority = 11, - .driver_task_stack_size = 2048, - .xCoreID = 0, - .new_dev_cb = new_dev_cb, - }; - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_install(&driver_config)); - - vTaskDelay(80); - TEST_ASSERT_TRUE_MESSAGE(new_dev_cb_called, "New device callback was not called\n"); - - // Clean-up - TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); - vTaskDelay(20); -} - -/* Following test case implements dual CDC-ACM USB device that can be used as mock device for CDC-ACM Host tests */ -void run_usb_dual_cdc_device(void); -TEST_CASE("mock_device_app", "[cdc_acm_device][ignore]") -{ - run_usb_dual_cdc_device(); - while (1) { - vTaskDelay(10); - } -} - -#endif +/* + * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: CC0-1.0 + */ + +#include "soc/soc_caps.h" +#if SOC_USB_OTG_SUPPORTED + +#include +#include "esp_system.h" +#include "freertos/FreeRTOS.h" +#include "freertos/task.h" +#include "esp_log.h" +#include "esp_err.h" + +#include "esp_private/usb_phy.h" +#include "usb/usb_host.h" +#include "usb/cdc_acm_host.h" +#include + +#include "esp_intr_alloc.h" + +#include "unity.h" +#include "soc/usb_wrap_struct.h" + +static uint8_t tx_buf[] = "HELLO"; +static uint8_t tx_buf2[] = "WORLD"; +static int nb_of_responses; +static int nb_of_responses2; +static usb_phy_handle_t phy_hdl = NULL; + +static void force_conn_state(bool connected, TickType_t delay_ticks) +{ + TEST_ASSERT_NOT_EQUAL(NULL, phy_hdl); + if (delay_ticks > 0) { + //Delay of 0 ticks causes a yield. So skip if delay_ticks is 0. + vTaskDelay(delay_ticks); + } + ESP_ERROR_CHECK(usb_phy_action(phy_hdl, (connected) ? USB_PHY_ACTION_HOST_ALLOW_CONN : USB_PHY_ACTION_HOST_FORCE_DISCONN)); +} + +void usb_lib_task(void *arg) +{ + // Initialize the internal USB PHY to connect to the USB OTG peripheral. We manually install the USB PHY for testing + usb_phy_config_t phy_config = { + .controller = USB_PHY_CTRL_OTG, + .target = USB_PHY_TARGET_INT, + .otg_mode = USB_OTG_MODE_HOST, + .otg_speed = USB_PHY_SPEED_UNDEFINED, //In Host mode, the speed is determined by the connected device + .gpio_conf = NULL, + }; + TEST_ASSERT_EQUAL(ESP_OK, usb_new_phy(&phy_config, &phy_hdl)); + // Install USB Host driver. Should only be called once in entire application + const usb_host_config_t host_config = { + .skip_phy_setup = true, + .intr_flags = ESP_INTR_FLAG_LEVEL1, + }; + TEST_ASSERT_EQUAL(ESP_OK, usb_host_install(&host_config)); + printf("USB Host installed\n"); + xTaskNotifyGive(arg); + + bool all_clients_gone = false; + bool all_dev_free = false; + while (!all_clients_gone || !all_dev_free) { + // Start handling system events + uint32_t event_flags; + usb_host_lib_handle_events(portMAX_DELAY, &event_flags); + if (event_flags & USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS) { + printf("No more clients\n"); + usb_host_device_free_all(); + all_clients_gone = true; + } + if (event_flags & USB_HOST_LIB_EVENT_FLAGS_ALL_FREE) { + printf("All devices freed\n"); + all_dev_free = true; + } + } + + // Clean up USB Host + vTaskDelay(10); // Short delay to allow clients clean-up + TEST_ASSERT_EQUAL(ESP_OK, usb_host_uninstall()); + TEST_ASSERT_EQUAL(ESP_OK, usb_del_phy(phy_hdl)); //Tear down USB PHY + phy_hdl = NULL; + vTaskDelete(NULL); +} + +void test_install_cdc_driver(void) +{ + // Create a task that will handle USB library events + TEST_ASSERT_EQUAL(pdTRUE, xTaskCreatePinnedToCore(usb_lib_task, "usb_lib", 4 * 4096, xTaskGetCurrentTaskHandle(), 10, NULL, 0)); + ulTaskNotifyTake(false, 1000); + + printf("Installing CDC-ACM driver\n"); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_install(NULL)); +} + +/* ------------------------------- Callbacks -------------------------------- */ +static void handle_rx(uint8_t *data, size_t data_len, void *arg) +{ + printf("Data received\n"); + nb_of_responses++; + TEST_ASSERT_EQUAL_STRING_LEN(data, arg, data_len); +} + +static void handle_rx2(uint8_t *data, size_t data_len, void *arg) +{ + printf("Data received 2\n"); + nb_of_responses2++; + TEST_ASSERT_EQUAL_STRING_LEN(data, arg, data_len); +} + +static void notif_cb(const cdc_acm_host_dev_event_data_t *event, void *user_ctx) +{ + switch (event->type) { + case CDC_ACM_HOST_ERROR: + printf("Error event %d\n", event->data.error); + break; + case CDC_ACM_HOST_SERIAL_STATE: + break; + case CDC_ACM_HOST_NETWORK_CONNECTION: + break; + case CDC_ACM_HOST_DEVICE_DISCONNECTED: + printf("Disconnection event\n"); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(event->data.cdc_hdl)); + xTaskNotifyGive(user_ctx); + break; + default: + assert(false); + } +} + +static bool new_dev_cb_called = false; +static void new_dev_cb(usb_device_handle_t usb_dev) +{ + new_dev_cb_called = true; + const usb_config_desc_t *config_desc; + const usb_device_desc_t *device_desc; + + // Get descriptors + TEST_ASSERT_EQUAL(ESP_OK, usb_host_get_device_descriptor(usb_dev, &device_desc)); + TEST_ASSERT_EQUAL(ESP_OK, usb_host_get_active_config_descriptor(usb_dev, &config_desc)); + + printf("New device connected. VID = 0x%04X PID = %04X\n", device_desc->idVendor, device_desc->idProduct); +} + +/* Basic test to check CDC communication: + * open/read/write/close device + * CDC-ACM specific commands: set/get_line_coding, set_control_line_state */ +TEST_CASE("read_write", "[cdc_acm]") +{ + nb_of_responses = 0; + cdc_acm_dev_hdl_t cdc_dev = NULL; + + test_install_cdc_driver(); + + const cdc_acm_host_device_config_t dev_config = { + .connection_timeout_ms = 500, + .out_buffer_size = 64, + .event_cb = notif_cb, + .data_cb = handle_rx, + .user_arg = tx_buf, + }; + + printf("Opening CDC-ACM device\n"); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); // 0x303A:0x4002 (TinyUSB Dual CDC device) + TEST_ASSERT_NOT_NULL(cdc_dev); + cdc_acm_host_desc_print(cdc_dev); + vTaskDelay(100); + + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_data_tx_blocking(cdc_dev, tx_buf, sizeof(tx_buf), 1000)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_data_tx_blocking(cdc_dev, tx_buf, sizeof(tx_buf), 1000)); + vTaskDelay(100); // Wait until responses are processed + + // We sent two messages, should get two responses + TEST_ASSERT_EQUAL(2, nb_of_responses); + + cdc_acm_line_coding_t line_coding_get; + const cdc_acm_line_coding_t line_coding_set = { + .dwDTERate = 9600, + .bDataBits = 7, + .bParityType = 1, + .bCharFormat = 1, + }; + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_line_coding_set(cdc_dev, &line_coding_set)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_line_coding_get(cdc_dev, &line_coding_get)); + TEST_ASSERT_EQUAL_MEMORY(&line_coding_set, &line_coding_get, sizeof(cdc_acm_line_coding_t)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_set_control_line_state(cdc_dev, true, false)); + + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); + + vTaskDelay(20); //Short delay to allow task to be cleaned up +} + +/* Test communication with multiple CDC-ACM devices from one thread */ +TEST_CASE("multiple_devices", "[cdc_acm]") +{ + nb_of_responses = 0; + nb_of_responses2 = 0; + + test_install_cdc_driver(); + + printf("Opening 2 CDC-ACM devices\n"); + cdc_acm_dev_hdl_t cdc_dev1, cdc_dev2; + cdc_acm_host_device_config_t dev_config = { + .connection_timeout_ms = 1000, + .out_buffer_size = 64, + .event_cb = notif_cb, + .data_cb = handle_rx, + .user_arg = tx_buf, + }; + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev1)); // 0x303A:0x4002 (TinyUSB Dual CDC device) + dev_config.data_cb = handle_rx2; + dev_config.user_arg = tx_buf2; + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 2, &dev_config, &cdc_dev2)); // 0x303A:0x4002 (TinyUSB Dual CDC device) + TEST_ASSERT_NOT_NULL(cdc_dev1); + TEST_ASSERT_NOT_NULL(cdc_dev2); + + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_data_tx_blocking(cdc_dev1, tx_buf, sizeof(tx_buf), 1000)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_data_tx_blocking(cdc_dev2, tx_buf2, sizeof(tx_buf2), 1000)); + + vTaskDelay(100); // Wait for RX callbacks + + // We sent two messages, should get two responses + TEST_ASSERT_EQUAL(1, nb_of_responses); + TEST_ASSERT_EQUAL(1, nb_of_responses2); + + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev1)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev2)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); + + //Short delay to allow task to be cleaned up + vTaskDelay(20); +} + +#define MULTIPLE_THREADS_TRANSFERS_NUM 5 +#define MULTIPLE_THREADS_TASKS_NUM 4 +void tx_task(void *arg) +{ + cdc_acm_dev_hdl_t cdc_dev = (cdc_acm_dev_hdl_t) arg; + // Send multiple transfers to make sure that some of them will run at the same time + for (int i = 0; i < MULTIPLE_THREADS_TRANSFERS_NUM; i++) { + // BULK endpoints + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_data_tx_blocking(cdc_dev, tx_buf, sizeof(tx_buf), 1000)); + + // CTRL endpoints + cdc_acm_line_coding_t line_coding_get; + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_line_coding_get(cdc_dev, &line_coding_get)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_set_control_line_state(cdc_dev, true, false)); + } + vTaskDelete(NULL); +} + +/** + * @brief Multiple threads test + * + * In this test, one CDC device is accessed from multiple threads. + * It has to be opened/closed just once, though. + */ +TEST_CASE("multiple_threads", "[cdc_acm]") +{ + nb_of_responses = 0; + cdc_acm_dev_hdl_t cdc_dev; + test_install_cdc_driver(); + + const cdc_acm_host_device_config_t dev_config = { + .connection_timeout_ms = 5000, + .out_buffer_size = 64, + .event_cb = notif_cb, + .data_cb = handle_rx, + .user_arg = tx_buf, + }; + + printf("Opening CDC-ACM device\n"); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); // 0x303A:0x4002 (TinyUSB Dual CDC device) + TEST_ASSERT_NOT_NULL(cdc_dev); + + // Create two tasks that will try to access cdc_dev + for (int i = 0; i < MULTIPLE_THREADS_TASKS_NUM; i++) { + TEST_ASSERT_EQUAL(pdTRUE, xTaskCreate(tx_task, "CDC TX", 4096, cdc_dev, i + 3, NULL)); + } + + // Wait until all tasks finish + vTaskDelay(pdMS_TO_TICKS(500)); + TEST_ASSERT_EQUAL(MULTIPLE_THREADS_TASKS_NUM * MULTIPLE_THREADS_TRANSFERS_NUM, nb_of_responses); + + // Clean-up + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); + vTaskDelay(20); +} + +/* Test CDC driver reaction to USB device sudden disconnection */ +TEST_CASE("sudden_disconnection", "[cdc_acm]") +{ + test_install_cdc_driver(); + + cdc_acm_dev_hdl_t cdc_dev; + cdc_acm_host_device_config_t dev_config = { + .connection_timeout_ms = 1000, + .out_buffer_size = 64, + .event_cb = notif_cb, + .data_cb = handle_rx + }; + dev_config.user_arg = xTaskGetCurrentTaskHandle(); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); + TEST_ASSERT_NOT_NULL(cdc_dev); + + force_conn_state(false, pdMS_TO_TICKS(10)); // Simulate device disconnection + TEST_ASSERT_EQUAL(1, ulTaskNotifyTake(false, pdMS_TO_TICKS(100))); // Notify will succeed only if CDC_ACM_HOST_DEVICE_DISCONNECTED notification was generated + + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); + vTaskDelay(20); //Short delay to allow task to be cleaned up +} + +/** + * @brief CDC-ACM error handling test + * + * There are multiple erroneous scenarios checked in this test: + * + * -# Install CDC-ACM driver without USB Host + * -# Open device without installed driver + * -# Uninstall driver before installing it + * -# Open non-existent device + * -# Open the same device twice + * -# Uninstall driver with open devices + * -# Send data that is too large + * -# Send unsupported CDC request + * -# Write to read-only device + */ +TEST_CASE("error_handling", "[cdc_acm]") +{ + cdc_acm_dev_hdl_t cdc_dev; + cdc_acm_host_device_config_t dev_config = { + .connection_timeout_ms = 500, + .out_buffer_size = 64, + .event_cb = notif_cb, + .data_cb = handle_rx + }; + + // Install CDC-ACM driver without USB Host + TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, cdc_acm_host_install(NULL)); + + // Open device without installed driver + TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); + + // Uninstall driver before installing it + TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, cdc_acm_host_uninstall()); + + // Properly install USB and CDC drivers + test_install_cdc_driver(); + + // Open non-existent device + TEST_ASSERT_EQUAL(ESP_ERR_NOT_FOUND, cdc_acm_host_open(0x303A, 0x1234, 0, &dev_config, &cdc_dev)); // 0x303A:0x1234 this device is not connected to USB Host + TEST_ASSERT_NULL(cdc_dev); + + // Open regular device + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); + TEST_ASSERT_NOT_NULL(cdc_dev); + + // Open one CDC-ACM device twice + cdc_acm_dev_hdl_t cdc_dev_test; + TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev_test)); + TEST_ASSERT_NULL(cdc_dev_test); + + // Uninstall driver with open devices + TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, cdc_acm_host_uninstall()); + + // Send data that is too large and NULL data + TEST_ASSERT_EQUAL(ESP_ERR_INVALID_SIZE, cdc_acm_host_data_tx_blocking(cdc_dev, tx_buf, 1024, 1000)); + TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, cdc_acm_host_data_tx_blocking(cdc_dev, NULL, 10, 1000)); + + // Change mode to read-only and try to write to it + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev)); + dev_config.out_buffer_size = 0; // Read-only device + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); + TEST_ASSERT_NOT_NULL(cdc_dev); + TEST_ASSERT_EQUAL(ESP_ERR_NOT_SUPPORTED, cdc_acm_host_data_tx_blocking(cdc_dev, tx_buf, sizeof(tx_buf), 1000)); + + // Send unsupported CDC request (TinyUSB accepts SendBreak command, eventhough it doesn't support it) + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_send_break(cdc_dev, 100)); + + // Clean-up + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); + vTaskDelay(20); +} + +TEST_CASE("custom_command", "[cdc_acm]") +{ + test_install_cdc_driver(); + + // Open device with only CTRL endpoint (endpoint no 0) + cdc_acm_dev_hdl_t cdc_dev; + const cdc_acm_host_device_config_t dev_config = { + .connection_timeout_ms = 500, + .out_buffer_size = 0, + .event_cb = notif_cb, + .data_cb = NULL + }; + + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_open(0x303A, 0x4002, 0, &dev_config, &cdc_dev)); + TEST_ASSERT_NOT_NULL(cdc_dev); + + // Corresponds to command: Set Control Line State, DTR on, RTS off + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_send_custom_request(cdc_dev, 0x21, 34, 1, 0, 0, NULL)); + + // Clean-up + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_close(cdc_dev)); + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); + vTaskDelay(20); +} + +TEST_CASE("new_device_connection", "[cdc_acm]") +{ + // Create a task that will handle USB library events + TEST_ASSERT_EQUAL(pdTRUE, xTaskCreatePinnedToCore(usb_lib_task, "usb_lib", 4 * 4096, xTaskGetCurrentTaskHandle(), 10, NULL, 0)); + ulTaskNotifyTake(false, 1000); + + printf("Installing CDC-ACM driver\n"); + const cdc_acm_host_driver_config_t driver_config = { + .driver_task_priority = 11, + .driver_task_stack_size = 2048, + .xCoreID = 0, + .new_dev_cb = new_dev_cb, + }; + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_install(&driver_config)); + + vTaskDelay(80); + TEST_ASSERT_TRUE_MESSAGE(new_dev_cb_called, "New device callback was not called\n"); + + // Clean-up + TEST_ASSERT_EQUAL(ESP_OK, cdc_acm_host_uninstall()); + vTaskDelay(20); +} + +/* Following test case implements dual CDC-ACM USB device that can be used as mock device for CDC-ACM Host tests */ +void run_usb_dual_cdc_device(void); +TEST_CASE("mock_device_app", "[cdc_acm_device][ignore]") +{ + run_usb_dual_cdc_device(); + while (1) { + vTaskDelay(10); + } +} + +#endif