From a30ebe3c14dd3d7b400bc92c22012a2e6badb810 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Tue, 23 Nov 2021 12:19:45 +0000 Subject: [PATCH 1/8] [Docs] Added usb.rst file --- docs/source/api/usb.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/source/api/usb.rst diff --git a/docs/source/api/usb.rst b/docs/source/api/usb.rst new file mode 100644 index 00000000000..bced0aff5fc --- /dev/null +++ b/docs/source/api/usb.rst @@ -0,0 +1,12 @@ +####### +USB API +####### + +About +----- + +USB as Device +************* + +USB as Host +*********** \ No newline at end of file From 90da36f8c7abcdad478e66d7fe37ca73be582f0b Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 13 Dec 2021 19:25:24 +0000 Subject: [PATCH 2/8] [Bug Fix] Added basic files for USB docs --- docs/source/api/usb.rst | 10 +++++++++- docs/source/libraries.rst | 1 + 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/source/api/usb.rst b/docs/source/api/usb.rst index bced0aff5fc..1369d8c19bf 100644 --- a/docs/source/api/usb.rst +++ b/docs/source/api/usb.rst @@ -2,6 +2,8 @@ USB API ####### +.. note:: This feature is only supported by ESP32-S2. + About ----- @@ -9,4 +11,10 @@ USB as Device ************* USB as Host -*********** \ No newline at end of file +*********** + +API Description +--------------- + +useStaticBuffers +**************** \ No newline at end of file diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst index 6275e603f2a..12dd8cfd37f 100644 --- a/docs/source/libraries.rst +++ b/docs/source/libraries.rst @@ -86,4 +86,5 @@ The Arduino ESP32 offers some unique APIs, described in this section: I2C RainMaker Reset Reason + USB Wi-Fi From 59b978b27c15d50c7ae88a0f058f0673c9a5b97a Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Thu, 16 Dec 2021 18:13:34 +0000 Subject: [PATCH 3/8] [Docs] Added structure for the USB API --- docs/source/api/usb.rst | 436 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 434 insertions(+), 2 deletions(-) diff --git a/docs/source/api/usb.rst b/docs/source/api/usb.rst index 1369d8c19bf..006e6949f42 100644 --- a/docs/source/api/usb.rst +++ b/docs/source/api/usb.rst @@ -7,14 +7,446 @@ USB API About ----- +The **Universal Serial Bus** is a widely used peripheral to exchange data between devices. USB was introduced on the ESP32-S2, supporting both device and host mode. + +To learn about the USB, see the `USB.org`_ for developers. + USB as Device ************* +In the device mode, the ESP32-S2 acts as an USB device, like a mouse or keyboard to be connected to a host device, like your computer or smartphone. + USB as Host *********** +The USB host mode, you can connect devices on the ESP32-S2, like external modems, mouse and keyboards. + +.. note:: This mode is still under development for the ESP32-S2. + API Description --------------- -useStaticBuffers -**************** \ No newline at end of file +USB Common +********** + +ESP USB +^^^^^^^ + +.. code-block:: arduino + + ESPUSB(size_t event_task_stack_size=2048, uint8_t event_task_priority=5); + +.. code-block:: arduino + + ~ESPUSB(); + +onEvent +^^^^^^^ + +.. code-block:: arduino + + void onEvent(esp_event_handler_t callback); + +.. code-block:: arduino + + void onEvent(arduino_usb_event_t event, esp_event_handler_t callback); + +VID +^^^ + +.. code-block:: arduino + + bool VID(uint16_t v); + +.. code-block:: arduino + + uint16_t VID(void); + +PID +^^^ + +.. code-block:: arduino + + bool PID(uint16_t p); + +.. code-block:: arduino + + uint16_t PID(void); + +firmwareVersion +^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + bool firmwareVersion(uint16_t version); + +.. code-block:: arduino + + uint16_t firmwareVersion(void); + +usbVersion +^^^^^^^^^^ + +.. code-block:: arduino + + bool usbVersion(uint16_t version); + +.. code-block:: arduino + + uint16_t usbVersion(void); + +usbPower +^^^^^^^^ + +.. code-block:: arduino + + bool usbPower(uint16_t mA); + +.. code-block:: arduino + + uint16_t usbPower(void); + +usbClass +^^^^^^^^ + +.. code-block:: arduino + + bool usbClass(uint8_t _class); + +.. code-block:: arduino + + uint8_t usbClass(void); + +usbSubClass +^^^^^^^^^^^ + +.. code-block:: arduino + + bool usbSubClass(uint8_t subClass); + +.. code-block:: arduino + + uint8_t usbSubClass(void); + +usbProtocol +^^^^^^^^^^^ + +.. code-block:: arduino + + bool usbProtocol(uint8_t protocol); + +.. code-block:: arduino + + uint8_t usbProtocol(void); + +usbAttributes +^^^^^^^^^^^^^ + +.. code-block:: arduino + + bool usbAttributes(uint8_t attr); + +.. code-block:: arduino + + uint8_t usbAttributes(void); + +webUSB +^^^^^^ + +.. code-block:: arduino + + bool webUSB(bool enabled); + +.. code-block:: arduino + + bool webUSB(void); + +productName +^^^^^^^^^^^ + +.. code-block:: arduino + + bool productName(const char * name); + +.. code-block:: arduino + + const char * productName(void); + +manufacturerName +^^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + bool manufacturerName(const char * name); + +.. code-block:: arduino + + const char * manufacturerName(void); + +serialNumber +^^^^^^^^^^^^ + +.. code-block:: arduino + + bool serialNumber(const char * name); + +.. code-block:: arduino + + const char * serialNumber(void); + +webUSBURL +^^^^^^^^^ + +.. code-block:: arduino + + bool webUSBURL(const char * name); + +.. code-block:: arduino + + const char * webUSBURL(void); + +enableDFU +^^^^^^^^^ + +.. code-block:: arduino + + bool enableDFU(); + +begin +^^^^^ + +.. code-block:: arduino + + bool begin(); + +USB MSC +******* + +USBMSC +^^^^^^ + +.. code-block:: arduino + + USBMSC(); + +.. code-block:: arduino + + ~USBMSC(); + +begin +^^^^^ + +.. code-block:: arduino + + bool begin(uint32_t block_count, uint16_t block_size); + +end +^^^ + +.. code-block:: arduino + + void end(); + +vendorID +^^^^^^^^ + +.. code-block:: arduino + + void vendorID(const char * vid);//max 8 chars + +productID +^^^^^^^^^ + +.. code-block:: arduino + + void productID(const char * pid);//max 16 chars + +productRevision +^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + void productRevision(const char * ver);//max 4 chars + +mediaPresent +^^^^^^^^^^^^ + +.. code-block:: arduino + + void mediaPresent(bool media_present); + +onStartStop +^^^^^^^^^^^ + +.. code-block:: arduino + + void onStartStop(msc_start_stop_cb cb); + +onRead +^^^^^^ + +.. code-block:: arduino + + void onRead(msc_read_cb cb); + +onWrite +^^^^^^^ + +.. code-block:: arduino + + void onWrite(msc_write_cb cb); + +USB CDC +******* + +USBCDC +^^^^^^ + +USBCDC +^^^^^^ + +.. code-block:: arduino + + USBCDC(uint8_t itf=0); + +.. code-block:: arduino + + ~USBCDC(); + +onEvent +^^^^^^^ + +.. code-block:: arduino + + void onEvent(esp_event_handler_t callback); + +.. code-block:: arduino + + void onEvent(arduino_usb_cdc_event_t event, esp_event_handler_t callback); + +setRxBufferSize +^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + size_t setRxBufferSize(size_t size); + +setTxTimeoutMs +^^^^^^^^^^^^^^ + +.. code-block:: arduino + + void setTxTimeoutMs(uint32_t timeout); + +begin +^^^^^ + +.. code-block:: arduino + + void begin(unsigned long baud=0); + +end +^^^ + +.. code-block:: arduino + + void end(); + +available +^^^^^^^^^ + +.. code-block:: arduino + + int available(void); + +availableForWrite +^^^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + int availableForWrite(void); + +peek +^^^^ + +.. code-block:: arduino + + int peek(void); + +read +^^^^ + +.. code-block:: arduino + + int read(void); + +.. code-block:: arduino + + size_t read(uint8_t *buffer, size_t size); + +write +^^^^^ + +.. code-block:: arduino + + size_t write(uint8_t); + +.. code-block:: arduino + + size_t write(const uint8_t *buffer, size_t size); + +flush +^^^^^ + +.. code-block:: arduino + + void flush(void); + +baudRate +^^^^^^^^ + +.. code-block:: arduino + + uint32_t baudRate(); + +setDebugOutput +^^^^^^^^^^^^^^ + +.. code-block:: arduino + + void setDebugOutput(bool); + +enableReboot +^^^^^^^^^^^^ + +.. code-block:: arduino + + void enableReboot(bool enable); + +rebootEnabled +^^^^^^^^^^^^^ + +.. code-block:: arduino + + bool rebootEnabled(void); + +Example Code +------------ + +There ara a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device. + +HIDVendor +********* + +.. literalinclude:: ../../../libraries/USB/examples/HIDVendor/HIDVendor.ino + :language: arduino + +FirmwareMSC +*********** + +.. literalinclude:: ../../../libraries/USB/examples/FirmwareMSC/FirmwareMSC.ino + :language: arduino + + + +.. _USB.org: https://www.usb.org/developers \ No newline at end of file From d7dbd85dae495f70d478ce83312f2cf3844fe3f4 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Fri, 17 Dec 2021 12:56:51 +0000 Subject: [PATCH 4/8] [Docs] First draft version for the USB docs --- docs/source/api/usb.rst | 238 +++++++++++++++++++++++++++++++++------- 1 file changed, 196 insertions(+), 42 deletions(-) diff --git a/docs/source/api/usb.rst b/docs/source/api/usb.rst index 006e6949f42..dc547e07a56 100644 --- a/docs/source/api/usb.rst +++ b/docs/source/api/usb.rst @@ -29,145 +29,218 @@ API Description USB Common ********** -ESP USB -^^^^^^^ - -.. code-block:: arduino - - ESPUSB(size_t event_task_stack_size=2048, uint8_t event_task_priority=5); - -.. code-block:: arduino - - ~ESPUSB(); +These are the common APIs for the USB driver. onEvent ^^^^^^^ +Event handling function to set the callback. + .. code-block:: arduino void onEvent(esp_event_handler_t callback); +Event handling function for the specific event. + .. code-block:: arduino void onEvent(arduino_usb_event_t event, esp_event_handler_t callback); +Where ``event`` can be: + +* ARDUINO_USB_ANY_EVENT +* ARDUINO_USB_STARTED_EVENT +* ARDUINO_USB_STOPPED_EVENT +* ARDUINO_USB_SUSPEND_EVENT +* ARDUINO_USB_RESUME_EVENT +* ARDUINO_USB_MAX_EVENT + VID ^^^ +Set the Vendor ID. This 16 bits identification is used to identify the company that develops the product. + +.. note:: You can't define your own VID. If you need your own VID, you need to buy one. See https://www.usb.org/getting-vendor-id for more details. + .. code-block:: arduino bool VID(uint16_t v); + +Get the Vendor ID. + .. code-block:: arduino uint16_t VID(void); +Returns the Vendor ID. The default value for the VID is: ``0x303A``. + PID ^^^ +Set the Product ID. This 16 bits identification is used to identify the product. + .. code-block:: arduino bool PID(uint16_t p); +Get the Product ID. + .. code-block:: arduino uint16_t PID(void); +Returns the Product ID. The default PID is: ``0x0002``. + firmwareVersion ^^^^^^^^^^^^^^^ +Set the firmware version. This is a 16 bits unsigned value. + .. code-block:: arduino bool firmwareVersion(uint16_t version); +Get the firmware version. + .. code-block:: arduino uint16_t firmwareVersion(void); +Return the 16 bits unsigned value. The default value is: ``0x100``. + usbVersion ^^^^^^^^^^ +Set the USB version. + .. code-block:: arduino bool usbVersion(uint16_t version); +Get the USB version. + .. code-block:: arduino uint16_t usbVersion(void); +Return the USB version. The default value is: ``0x200`` (USB 2.0). + usbPower ^^^^^^^^ +Set the USB power as mA (current). + +.. note:: This configuration does not change the physical power output. This is only used for the USB device information. + .. code-block:: arduino bool usbPower(uint16_t mA); +Get the USB power configuration. + .. code-block:: arduino uint16_t usbPower(void); +Return the current in mA. The default value is: ``0x500`` (500mA). + usbClass ^^^^^^^^ +Set the USB class. + .. code-block:: arduino bool usbClass(uint8_t _class); +Get the USB class. + .. code-block:: arduino uint8_t usbClass(void); +Return the USB class. The default value is: ``TUSB_CLASS_MISC``. + usbSubClass ^^^^^^^^^^^ +Set the USB sub-class. + .. code-block:: arduino bool usbSubClass(uint8_t subClass); +Get the USB sub-class. + .. code-block:: arduino uint8_t usbSubClass(void); +Return the USB sub-class. The default value is: ``MISC_SUBCLASS_COMMON``. + usbProtocol ^^^^^^^^^^^ +Define the USB protocol. + .. code-block:: arduino bool usbProtocol(uint8_t protocol); +Get the USB protocol. + .. code-block:: arduino uint8_t usbProtocol(void); +Return the USB protocol. The default value is: ``MISC_PROTOCOL_IAD`` + usbAttributes ^^^^^^^^^^^^^ +Set the USB attributes. + .. code-block:: arduino bool usbAttributes(uint8_t attr); +Get the USB attributes. + .. code-block:: arduino uint8_t usbAttributes(void); +Return the USB attributes. The default value is: ``TUSB_DESC_CONFIG_ATT_SELF_POWERED`` + webUSB ^^^^^^ +This function is used to enable the ``webUSB`` functionality. + .. code-block:: arduino bool webUSB(bool enabled); +This function is used to get the ``webUSB`` setting. + .. code-block:: arduino bool webUSB(void); +Return the ``webUSB`` setting (`Enabled` or `Disabled`) + productName ^^^^^^^^^^^ +This function is used to define the product name. + .. code-block:: arduino bool productName(const char * name); - + +This function is used to get the product's name. + .. code-block:: arduino const char * productName(void); @@ -175,10 +248,14 @@ productName manufacturerName ^^^^^^^^^^^^^^^^ +This function is used to define the manufacturer name. + .. code-block:: arduino bool manufacturerName(const char * name); - + +This function is used to get the manufacturer's name. + .. code-block:: arduino const char * manufacturerName(void); @@ -186,28 +263,42 @@ manufacturerName serialNumber ^^^^^^^^^^^^ +This function is used to define the serial number. + .. code-block:: arduino bool serialNumber(const char * name); - + +This function is used to get the serial number. + .. code-block:: arduino const char * serialNumber(void); +The default serial number is: ``0``. + webUSBURL ^^^^^^^^^ +This function is used to define the ``webUSBURL``. + .. code-block:: arduino bool webUSBURL(const char * name); +This function is used to get the ``webUSBURL``. + .. code-block:: arduino const char * webUSBURL(void); +The default ``webUSBURL`` is: https://espressif.github.io/arduino-esp32/webusb.html + enableDFU ^^^^^^^^^ +This function is used to enable the DFU capability. + .. code-block:: arduino bool enableDFU(); @@ -215,6 +306,8 @@ enableDFU begin ^^^^^ +This function is used to start the peripheral using the default configuration. + .. code-block:: arduino bool begin(); @@ -222,27 +315,31 @@ begin USB MSC ******* -USBMSC -^^^^^^ - -.. code-block:: arduino +USB Mass Storage Class API. This class makes the device accessible as a mass storage device and allows you to transfer data between the host and the device. - USBMSC(); - -.. code-block:: arduino - - ~USBMSC(); +One of the examples for this mode is to flash the device by dropping the firmware binary like a flash memory device when connecting the ESP32-S2 to the host computer. begin ^^^^^ +This function is used to start the peripheral using the default MSC configuration. + .. code-block:: arduino bool begin(uint32_t block_count, uint16_t block_size); +Where: + +* ``block_count`` set the disk sector count. +* ``block_size`` set the disk sector size. + +This function will return ``true`` if the configuration was successful. + end ^^^ +This function will finish the peripheral as MSC and release all the allocated resources. After calling ``end`` you need to use ``begin`` again in order to initialize the USB MSC driver again. + .. code-block:: arduino void end(); @@ -250,6 +347,8 @@ end vendorID ^^^^^^^^ +This function is used to define the vendor ID. + .. code-block:: arduino void vendorID(const char * vid);//max 8 chars @@ -257,6 +356,8 @@ vendorID productID ^^^^^^^^^ +This function is used to define the product ID. + .. code-block:: arduino void productID(const char * pid);//max 16 chars @@ -264,6 +365,8 @@ productID productRevision ^^^^^^^^^^^^^^^ +This function is used to define the product revision. + .. code-block:: arduino void productRevision(const char * ver);//max 4 chars @@ -271,6 +374,8 @@ productRevision mediaPresent ^^^^^^^^^^^^ +Set the ``mediaPresent`` configuration. + .. code-block:: arduino void mediaPresent(bool media_present); @@ -278,6 +383,8 @@ mediaPresent onStartStop ^^^^^^^^^^^ +Set the ``onStartStop`` callback function. + .. code-block:: arduino void onStartStop(msc_start_stop_cb cb); @@ -285,6 +392,8 @@ onStartStop onRead ^^^^^^ +Set the ``onRead`` callback function. + .. code-block:: arduino void onRead(msc_read_cb cb); @@ -292,6 +401,8 @@ onRead onWrite ^^^^^^^ +Set the ``onWrite`` callback function. + .. code-block:: arduino void onWrite(msc_write_cb cb); @@ -299,23 +410,15 @@ onWrite USB CDC ******* -USBCDC -^^^^^^ - -USBCDC -^^^^^^ +USB Communications Device Class API. This class is used to enable communication between the host and the device. -.. code-block:: arduino - - USBCDC(uint8_t itf=0); - -.. code-block:: arduino - - ~USBCDC(); +This class is often used to enable serial communication and can be used to flash the firmware on the ESP32-S2 without the external USB to Serial chip. onEvent ^^^^^^^ +Event handling functions. + .. code-block:: arduino void onEvent(esp_event_handler_t callback); @@ -324,9 +427,22 @@ onEvent 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_MAX_EVENT + setRxBufferSize ^^^^^^^^^^^^^^^ +The ``setRxBufferSize`` function is used to set the size of the RX buffer. + .. code-block:: arduino size_t setRxBufferSize(size_t size); @@ -334,6 +450,8 @@ setRxBufferSize setTxTimeoutMs ^^^^^^^^^^^^^^ +This function is used to define the time to reach the timeout for the TX. + .. code-block:: arduino void setTxTimeoutMs(uint32_t timeout); @@ -341,13 +459,21 @@ setTxTimeoutMs begin ^^^^^ +This function is used to start the peripheral using the default CDC configuration. + .. code-block:: arduino - void begin(unsigned long baud=0); + 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. + .. code-block:: arduino void end(); @@ -355,13 +481,19 @@ end available ^^^^^^^^^ +This function will return if there are messages in the queue. + .. code-block:: arduino 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. + .. code-block:: arduino int availableForWrite(void); @@ -369,6 +501,8 @@ availableForWrite peek ^^^^ +This function is used to ``peek`` messages from the queue. + .. code-block:: arduino int peek(void); @@ -376,28 +510,36 @@ peek read ^^^^ -.. code-block:: arduino - - int read(void); +This function is used to read the bytes available. .. code-block:: arduino 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 ^^^^^ -.. code-block:: arduino - - size_t write(uint8_t); +This function is used to write the message. .. code-block:: arduino 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. + .. code-block:: arduino void flush(void); @@ -405,6 +547,8 @@ flush baudRate ^^^^^^^^ +This function is used to get the ``baudRate``. + .. code-block:: arduino uint32_t baudRate(); @@ -412,6 +556,8 @@ baudRate setDebugOutput ^^^^^^^^^^^^^^ +This function will enable the debug output, usually from the `UART0`, to the USB CDC. + .. code-block:: arduino void setDebugOutput(bool); @@ -419,6 +565,8 @@ setDebugOutput enableReboot ^^^^^^^^^^^^ +This function enables the device to reboot by the DTR as RTS signals. + .. code-block:: arduino void enableReboot(bool enable); @@ -426,6 +574,8 @@ enableReboot rebootEnabled ^^^^^^^^^^^^^ +This function will return if the reboot is enabled. + .. code-block:: arduino bool rebootEnabled(void); @@ -433,7 +583,7 @@ rebootEnabled Example Code ------------ -There ara a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device. +There are a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device. HIDVendor ********* @@ -447,6 +597,10 @@ FirmwareMSC .. literalinclude:: ../../../libraries/USB/examples/FirmwareMSC/FirmwareMSC.ino :language: arduino +Mouse +***** +.. literalinclude:: ../../../libraries/USB/examples/Mouse/ButtonMouseControl/ButtonMouseControl.ino + :language: arduino .. _USB.org: https://www.usb.org/developers \ No newline at end of file From 921f86ca4d7641d483e592897e5260a25f52364b Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 20 Dec 2021 18:17:47 +0000 Subject: [PATCH 5/8] [Docs] Splited USB CDC and MSC plus some changes based on the PR review. --- docs/source/api/usb.rst | 297 +----------------------------------- docs/source/api/usb_cdc.rst | 204 +++++++++++++++++++++++++ docs/source/api/usb_msc.rst | 109 +++++++++++++ 3 files changed, 321 insertions(+), 289 deletions(-) create mode 100644 docs/source/api/usb_cdc.rst create mode 100644 docs/source/api/usb_msc.rst diff --git a/docs/source/api/usb.rst b/docs/source/api/usb.rst index dc547e07a56..add76b1d3ec 100644 --- a/docs/source/api/usb.rst +++ b/docs/source/api/usb.rst @@ -2,7 +2,7 @@ USB API ####### -.. note:: This feature is only supported by ESP32-S2. +.. note:: This feature is only supported on ESP chips that have USB peripheral, like the ESP32-S2 and ESP32-S3. Some chips, like the ESP32-C3 include native CDC+JTAG peripheral that is not covered here. About ----- @@ -26,6 +26,13 @@ The USB host mode, you can connect devices on the ESP32-S2, like external modems API Description --------------- +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + USB CDC + USB MSC + USB Common ********** @@ -312,295 +319,7 @@ This function is used to start the peripheral using the default configuration. bool begin(); -USB MSC -******* - -USB Mass Storage Class API. This class makes the device accessible as a mass storage device and allows you to transfer data between the host and the device. - -One of the examples for this mode is to flash the device by dropping the firmware binary like a flash memory device when connecting the ESP32-S2 to the host computer. - -begin -^^^^^ - -This function is used to start the peripheral using the default MSC configuration. - -.. code-block:: arduino - - bool begin(uint32_t block_count, uint16_t block_size); - -Where: - -* ``block_count`` set the disk sector count. -* ``block_size`` set the disk sector size. - -This function will return ``true`` if the configuration was successful. - -end -^^^ - -This function will finish the peripheral as MSC and release all the allocated resources. After calling ``end`` you need to use ``begin`` again in order to initialize the USB MSC driver again. - -.. code-block:: arduino - - void end(); - -vendorID -^^^^^^^^ - -This function is used to define the vendor ID. - -.. code-block:: arduino - - void vendorID(const char * vid);//max 8 chars - -productID -^^^^^^^^^ - -This function is used to define the product ID. - -.. code-block:: arduino - - void productID(const char * pid);//max 16 chars - -productRevision -^^^^^^^^^^^^^^^ - -This function is used to define the product revision. - -.. code-block:: arduino - - void productRevision(const char * ver);//max 4 chars - -mediaPresent -^^^^^^^^^^^^ - -Set the ``mediaPresent`` configuration. - -.. code-block:: arduino - - void mediaPresent(bool media_present); - -onStartStop -^^^^^^^^^^^ - -Set the ``onStartStop`` callback function. - -.. code-block:: arduino - - void onStartStop(msc_start_stop_cb cb); - -onRead -^^^^^^ - -Set the ``onRead`` callback function. - -.. code-block:: arduino - - void onRead(msc_read_cb cb); - -onWrite -^^^^^^^ - -Set the ``onWrite`` callback function. - -.. code-block:: arduino - - void onWrite(msc_write_cb cb); - -USB CDC -******* - -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-S2 without the external USB to Serial chip. - -onEvent -^^^^^^^ - -Event handling functions. - -.. code-block:: arduino - - void onEvent(esp_event_handler_t callback); - -.. code-block:: arduino - - 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_MAX_EVENT - -setRxBufferSize -^^^^^^^^^^^^^^^ - -The ``setRxBufferSize`` function is used to set the size of the RX buffer. - -.. code-block:: arduino - - size_t setRxBufferSize(size_t size); - -setTxTimeoutMs -^^^^^^^^^^^^^^ - -This function is used to define the time to reach the timeout for the TX. - -.. code-block:: arduino - - void setTxTimeoutMs(uint32_t timeout); - -begin -^^^^^ - -This function is used to start the peripheral using the default CDC configuration. - -.. code-block:: arduino - - 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. - -.. code-block:: arduino - - void end(); - -available -^^^^^^^^^ - -This function will return if there are messages in the queue. - -.. code-block:: arduino - - 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. - -.. code-block:: arduino - - int availableForWrite(void); - -peek -^^^^ - -This function is used to ``peek`` messages from the queue. - -.. code-block:: arduino - - int peek(void); - -read -^^^^ - -This function is used to read the bytes available. - -.. code-block:: arduino - - 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. - -.. code-block:: arduino - - 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. - -.. code-block:: arduino - - void flush(void); - -baudRate -^^^^^^^^ - -This function is used to get the ``baudRate``. - -.. code-block:: arduino - - uint32_t baudRate(); - -setDebugOutput -^^^^^^^^^^^^^^ - -This function will enable the debug output, usually from the `UART0`, to the USB CDC. - -.. code-block:: arduino - - void setDebugOutput(bool); - -enableReboot -^^^^^^^^^^^^ - -This function enables the device to reboot by the DTR as RTS signals. - -.. code-block:: arduino - - void enableReboot(bool enable); - -rebootEnabled -^^^^^^^^^^^^^ - -This function will return if the reboot is enabled. - -.. code-block:: arduino - - bool rebootEnabled(void); - Example Code ------------ There are a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device. - -HIDVendor -********* - -.. literalinclude:: ../../../libraries/USB/examples/HIDVendor/HIDVendor.ino - :language: arduino - -FirmwareMSC -*********** - -.. literalinclude:: ../../../libraries/USB/examples/FirmwareMSC/FirmwareMSC.ino - :language: arduino - -Mouse -***** - -.. literalinclude:: ../../../libraries/USB/examples/Mouse/ButtonMouseControl/ButtonMouseControl.ino - :language: arduino - -.. _USB.org: https://www.usb.org/developers \ No newline at end of file diff --git a/docs/source/api/usb_cdc.rst b/docs/source/api/usb_cdc.rst new file mode 100644 index 00000000000..8b1d878a03c --- /dev/null +++ b/docs/source/api/usb_cdc.rst @@ -0,0 +1,204 @@ +####### +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-S2 without the external USB to Serial chip. + +APIs +**** + +onEvent +^^^^^^^ + +Event handling functions. + +.. code-block:: arduino + + void onEvent(esp_event_handler_t callback); + +.. code-block:: arduino + + 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_MAX_EVENT + +setRxBufferSize +^^^^^^^^^^^^^^^ + +The ``setRxBufferSize`` function is used to set the size of the RX buffer. + +.. code-block:: arduino + + size_t setRxBufferSize(size_t size); + +setTxTimeoutMs +^^^^^^^^^^^^^^ + +This function is used to define the time to reach the timeout for the TX. + +.. code-block:: arduino + + void setTxTimeoutMs(uint32_t timeout); + +begin +^^^^^ + +This function is used to start the peripheral using the default CDC configuration. + +.. code-block:: arduino + + 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. + +.. code-block:: arduino + + void end(); + +available +^^^^^^^^^ + +This function will return if there are messages in the queue. + +.. code-block:: arduino + + 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. + +.. code-block:: arduino + + int availableForWrite(void); + +peek +^^^^ + +This function is used to ``peek`` messages from the queue. + +.. code-block:: arduino + + int peek(void); + +read +^^^^ + +This function is used to read the bytes available. + +.. code-block:: arduino + + 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. + +.. code-block:: arduino + + 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. + +.. code-block:: arduino + + void flush(void); + +baudRate +^^^^^^^^ + +This function is used to get the ``baudRate``. + +.. code-block:: arduino + + uint32_t baudRate(); + +setDebugOutput +^^^^^^^^^^^^^^ + +This function will enable the debug output, usually from the `UART0`, to the USB CDC. + +.. code-block:: arduino + + void setDebugOutput(bool); + +enableReboot +^^^^^^^^^^^^ + +This function enables the device to reboot by the DTR as RTS signals. + +.. code-block:: arduino + + void enableReboot(bool enable); + +rebootEnabled +^^^^^^^^^^^^^ + +This function will return if the reboot is enabled. + +.. code-block:: arduino + + bool rebootEnabled(void); + +Example Code +------------ + +There are a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device. + +HIDVendor +********* + +.. literalinclude:: ../../../libraries/USB/examples/HIDVendor/HIDVendor.ino + :language: arduino + +FirmwareMSC +*********** + +.. literalinclude:: ../../../libraries/USB/examples/FirmwareMSC/FirmwareMSC.ino + :language: arduino + +Mouse +***** + +.. literalinclude:: ../../../libraries/USB/examples/Mouse/ButtonMouseControl/ButtonMouseControl.ino + :language: arduino + +.. _USB.org: https://www.usb.org/developers \ No newline at end of file diff --git a/docs/source/api/usb_msc.rst b/docs/source/api/usb_msc.rst new file mode 100644 index 00000000000..ad86d392d62 --- /dev/null +++ b/docs/source/api/usb_msc.rst @@ -0,0 +1,109 @@ +####### +USB MSC +####### + +.. note:: This feature is only supported by ESP32-S2. + +About +----- + +USB Mass Storage Class API. This class makes the device accessible as a mass storage device and allows you to transfer data between the host and the device. + +One of the examples for this mode is to flash the device by dropping the firmware binary like a flash memory device when connecting the ESP32 to the host computer. + +APIs +**** + +begin +^^^^^ + +This function is used to start the peripheral using the default MSC configuration. + +.. code-block:: arduino + + bool begin(uint32_t block_count, uint16_t block_size); + +Where: + +* ``block_count`` set the disk sector count. +* ``block_size`` set the disk sector size. + +This function will return ``true`` if the configuration was successful. + +end +^^^ + +This function will finish the peripheral as MSC and release all the allocated resources. After calling ``end`` you need to use ``begin`` again in order to initialize the USB MSC driver again. + +.. code-block:: arduino + + void end(); + +vendorID +^^^^^^^^ + +This function is used to define the vendor ID. + +.. code-block:: arduino + + void vendorID(const char * vid);//max 8 chars + +productID +^^^^^^^^^ + +This function is used to define the product ID. + +.. code-block:: arduino + + void productID(const char * pid);//max 16 chars + +productRevision +^^^^^^^^^^^^^^^ + +This function is used to define the product revision. + +.. code-block:: arduino + + void productRevision(const char * ver);//max 4 chars + +mediaPresent +^^^^^^^^^^^^ + +Set the ``mediaPresent`` configuration. + +.. code-block:: arduino + + void mediaPresent(bool media_present); + +onStartStop +^^^^^^^^^^^ + +Set the ``onStartStop`` callback function. + +.. code-block:: arduino + + void onStartStop(msc_start_stop_cb cb); + +onRead +^^^^^^ + +Set the ``onRead`` callback function. + +.. code-block:: arduino + + void onRead(msc_read_cb cb); + +onWrite +^^^^^^^ + +Set the ``onWrite`` callback function. + +.. code-block:: arduino + + void onWrite(msc_write_cb cb); + +FirmwareMSC +*********** + +.. literalinclude:: ../../../libraries/USB/examples/FirmwareMSC/FirmwareMSC.ino + :language: arduino From 9a7408313709bb6f48a933783412b8683862153c Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 20 Dec 2021 18:22:16 +0000 Subject: [PATCH 6/8] [Docs] Added more description on the USB classes section. --- docs/source/api/usb.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/source/api/usb.rst b/docs/source/api/usb.rst index add76b1d3ec..e67b9afb411 100644 --- a/docs/source/api/usb.rst +++ b/docs/source/api/usb.rst @@ -7,28 +7,32 @@ USB API About ----- -The **Universal Serial Bus** is a widely used peripheral to exchange data between devices. USB was introduced on the ESP32-S2, supporting both device and host mode. +The **Universal Serial Bus** is a widely used peripheral to exchange data between devices. USB was introduced on the ESP32, supporting both device and host mode. To learn about the USB, see the `USB.org`_ for developers. USB as Device ************* -In the device mode, the ESP32-S2 acts as an USB device, like a mouse or keyboard to be connected to a host device, like your computer or smartphone. +In the device mode, the ESP32 acts as an USB device, like a mouse or keyboard to be connected to a host device, like your computer or smartphone. USB as Host *********** -The USB host mode, you can connect devices on the ESP32-S2, like external modems, mouse and keyboards. +The USB host mode, you can connect devices on the ESP32, like external modems, mouse and keyboards. -.. note:: This mode is still under development for the ESP32-S2. +.. note:: This mode is still under development for the ESP32. API Description --------------- +This is the common USB API description. + +For more supported USB classes implementation, see the following sections: + .. toctree:: - :maxdepth: 2 - :caption: Contents: + :maxdepth: 1 + :caption: Classes: USB CDC USB MSC From 0a9aa743ac982c274ac4e74c0d3214d53d5ea802 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 20 Dec 2021 18:24:16 +0000 Subject: [PATCH 7/8] [Docs] Fixed missing usb.org link ref --- docs/source/api/usb.rst | 2 ++ docs/source/api/usb_cdc.rst | 2 +- docs/source/api/usb_msc.rst | 2 ++ 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/source/api/usb.rst b/docs/source/api/usb.rst index e67b9afb411..94261185f61 100644 --- a/docs/source/api/usb.rst +++ b/docs/source/api/usb.rst @@ -327,3 +327,5 @@ Example Code ------------ There are a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device. + +.. _USB.org: https://www.usb.org/developers diff --git a/docs/source/api/usb_cdc.rst b/docs/source/api/usb_cdc.rst index 8b1d878a03c..7faedfca037 100644 --- a/docs/source/api/usb_cdc.rst +++ b/docs/source/api/usb_cdc.rst @@ -201,4 +201,4 @@ Mouse .. literalinclude:: ../../../libraries/USB/examples/Mouse/ButtonMouseControl/ButtonMouseControl.ino :language: arduino -.. _USB.org: https://www.usb.org/developers \ No newline at end of file +.. _USB.org: https://www.usb.org/developers diff --git a/docs/source/api/usb_msc.rst b/docs/source/api/usb_msc.rst index ad86d392d62..b66560cf1f6 100644 --- a/docs/source/api/usb_msc.rst +++ b/docs/source/api/usb_msc.rst @@ -107,3 +107,5 @@ FirmwareMSC .. literalinclude:: ../../../libraries/USB/examples/FirmwareMSC/FirmwareMSC.ino :language: arduino + +.. _USB.org: https://www.usb.org/developers From 81b5d6a1010929f6ae5644eef76939668aa4a6dd Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Tue, 21 Dec 2021 10:35:51 +0000 Subject: [PATCH 8/8] [Docs] Revision on CDC and MSC examples and minor fixes --- docs/source/api/usb_cdc.rst | 20 ++++---------------- docs/source/api/usb_msc.rst | 7 +++++-- 2 files changed, 9 insertions(+), 18 deletions(-) diff --git a/docs/source/api/usb_cdc.rst b/docs/source/api/usb_cdc.rst index 7faedfca037..1c0b04f2f3c 100644 --- a/docs/source/api/usb_cdc.rst +++ b/docs/source/api/usb_cdc.rst @@ -7,7 +7,7 @@ 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-S2 without the external USB to Serial chip. +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 **** @@ -181,24 +181,12 @@ This function will return if the reboot is enabled. Example Code ------------ -There are a collection of USB device examples on the project GitHub, including Firmware MSC update, USB CDC, HID and composite device. +Here is an example of how to use the USB CDC. -HIDVendor +USBSerial ********* -.. literalinclude:: ../../../libraries/USB/examples/HIDVendor/HIDVendor.ino - :language: arduino - -FirmwareMSC -*********** - -.. literalinclude:: ../../../libraries/USB/examples/FirmwareMSC/FirmwareMSC.ino - :language: arduino - -Mouse -***** - -.. literalinclude:: ../../../libraries/USB/examples/Mouse/ButtonMouseControl/ButtonMouseControl.ino +.. literalinclude:: ../../../libraries/USB/examples/USBSerial/USBSerial.ino :language: arduino .. _USB.org: https://www.usb.org/developers diff --git a/docs/source/api/usb_msc.rst b/docs/source/api/usb_msc.rst index b66560cf1f6..846e72e8db0 100644 --- a/docs/source/api/usb_msc.rst +++ b/docs/source/api/usb_msc.rst @@ -2,8 +2,6 @@ USB MSC ####### -.. note:: This feature is only supported by ESP32-S2. - About ----- @@ -102,6 +100,11 @@ Set the ``onWrite`` callback function. void onWrite(msc_write_cb cb); +Example Code +------------ + +Here is an example of how to use the USB MSC. + FirmwareMSC ***********