From bbed8d5262bab3c9e223df07b4989ec515e15b69 Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Thu, 29 Aug 2024 11:17:48 -0300 Subject: [PATCH 01/12] feat(hw_cdc): creates documentation for the example Adds a README file that exaplains the example. --- .../hw_cdc_hello_world/README.md | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 idf_component_examples/hw_cdc_hello_world/README.md diff --git a/idf_component_examples/hw_cdc_hello_world/README.md b/idf_component_examples/hw_cdc_hello_world/README.md new file mode 100644 index 00000000000..8203a970d70 --- /dev/null +++ b/idf_component_examples/hw_cdc_hello_world/README.md @@ -0,0 +1,63 @@ +| Supported Targets | ESP32-C3 | ESP32-C6 | ESP32-H2 | ESP32-S3 | +| ----------------- | -------- | -------- | -------- | -------- | + +# _HW Serial USB CDC example_ + +This is the simplest buildable example made to be used as a template for new projects running Arduino-ESP32 as an ESP-IDF component that will redefine the `Serial` interface to be attached to the USB CDC Harware Serial port.\ +See [arduino-esp32](https://components.espressif.com/components/espressif/arduino-esp32) in ESP Registry. + +## How to use example + +After cloning this repository, go to the `hw_cdc_hello_world` folder and select the target by executing\ +`idf.py set-target `.\ +`` can be one of the installed IDF version supported targets. + +It is possible to just clone this folder be executing\ +`idf.py create-project-from-example "espressif/arduino-esp32^3.0.5:hw_cdc_hello_world"` + +For IDF 5.1.x and forward, the list of targets that support Hardware USB CDC are, at least: esp32s3, esp32c3, esp32c6 and esp32h2.\ +Then just run command: `idf.py build` or `idf.py -p USB_PORT flash monitor`. + +Usually, it is necessary to make the ESP32 SoC to enter in `Download Mode` before uploading the firmware.\ +After that, just press `RESET/EN` to start the new firmware. + +## Example folder contents + +The project **hw_serial_example** contains one source file in C++ language [main.cpp](main/main.cpp). The file is located in folder [main](main). + +ESP-IDF projects are built using CMake. The project building configuration is contained in `CMakeLists.txt` +file that provide a set of directives and instructions describing the project's source files and targets +(executable, library, or both). + +Below is the minimum list of files in the project folder. + +``` +├── CMakeLists.txt Global project CMake configuration file +├── sdkconfig.defaults sdkconfig setting for an Arduino project +├── main +│   ├── CMakeLists.txt Arduino sketch CMake configuration file +│ ├── idf_component.yml List of IDF components necessary to build the project +│   └── main.cpp Arduino Sketch code - don't forget to add "#include " on it +└── README.md This is the file you are currently reading +``` + +## Configuring the Hardware USB CDC Serial + +ESP32 Arduino has two macro defined symbols that control what `Serial` symbol will represent. +Default `Serial` is the UART0 from `HardwareSerial` class. + +`Serial` can be changed to be attached to the HW Serial JTAG port fro the SoC. +In order to make it work, it is necessary to define 2 symbols: `ARDUINO_USB_CDC_ON_BOOT` and `ARDUINO_USB_MODE` to `1`. +This is achieved by adding a couple lines to the [Project Folder CMakeLists.txt](CMakeLists.txt) file. + + +``` +# Adds necessary definitions for compiling it using Serial symbol attached to the HW USB CDC port +list(APPEND compile_definitions "ARDUINO_USB_CDC_ON_BOOT=1") +list(APPEND compile_definitions "ARDUINO_USB_MODE=1") + +``` + +Those two lines will add a `-DSYMBOL=VAL` when compiling every source code file. + +In order to make sure that it is actually working correctly, the [sketch](main/main.cpp) will execute `Serial.begin();` with no baudrate, which only works for USB CDC. From 50778327ffcde03882718d954d8ce8dc81f38e05 Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Thu, 29 Aug 2024 11:21:01 -0300 Subject: [PATCH 02/12] feat(hw_cdc): create cmake config file Adds necessary CMakeLists.txt file to the project with the HW CDC defines that will enable it. --- .../hw_cdc_hello_world/CMakeLists.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 idf_component_examples/hw_cdc_hello_world/CMakeLists.txt diff --git a/idf_component_examples/hw_cdc_hello_world/CMakeLists.txt b/idf_component_examples/hw_cdc_hello_world/CMakeLists.txt new file mode 100644 index 00000000000..16bb1063af3 --- /dev/null +++ b/idf_component_examples/hw_cdc_hello_world/CMakeLists.txt @@ -0,0 +1,12 @@ +# For more information about build system see +# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html +# The following five lines of boilerplate have to be in your project's +# CMakeLists in this exact order for cmake to work correctly +cmake_minimum_required(VERSION 3.16) +include($ENV{IDF_PATH}/tools/cmake/project.cmake) + +# Adds necessary definitions for compiling it using Serial symbol attached to the HW USB CDC port +list(APPEND compile_definitions "ARDUINO_USB_CDC_ON_BOOT=1") +list(APPEND compile_definitions "ARDUINO_USB_MODE=1") + +project(hw_cdc_hello_world) From 03d570e072644ca537ea610639d19dd2e3d0711e Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Thu, 29 Aug 2024 11:22:48 -0300 Subject: [PATCH 03/12] feat(hw_cdc): create sdkconfig.defaults Adds necessary and minimum sdkconfig settings in order to make Arduino run as IDF Compoenent. --- .../hw_cdc_hello_world/sdkconfig.defaults | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 idf_component_examples/hw_cdc_hello_world/sdkconfig.defaults diff --git a/idf_component_examples/hw_cdc_hello_world/sdkconfig.defaults b/idf_component_examples/hw_cdc_hello_world/sdkconfig.defaults new file mode 100644 index 00000000000..bb723653f8a --- /dev/null +++ b/idf_component_examples/hw_cdc_hello_world/sdkconfig.defaults @@ -0,0 +1,12 @@ +# +# Arduino ESP32 +# +CONFIG_AUTOSTART_ARDUINO=y +# end of Arduino ESP32 + +# +# FREERTOS +# +CONFIG_FREERTOS_HZ=1000 +# end of FREERTOS +# end of Component config From ab2f5407a7efa6a75ed681e5f610dc484cc790e7 Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Thu, 29 Aug 2024 11:26:46 -0300 Subject: [PATCH 04/12] feat(hw_cdc): create cmake config file Create the Arduino Sketch source code CMakeLists.txt file that will include all source code files and header files in the proejct. --- idf_component_examples/hw_cdc_hello_world/main/CMakeLists.txt | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 idf_component_examples/hw_cdc_hello_world/main/CMakeLists.txt diff --git a/idf_component_examples/hw_cdc_hello_world/main/CMakeLists.txt b/idf_component_examples/hw_cdc_hello_world/main/CMakeLists.txt new file mode 100644 index 00000000000..25a78dec2a6 --- /dev/null +++ b/idf_component_examples/hw_cdc_hello_world/main/CMakeLists.txt @@ -0,0 +1,4 @@ +idf_component_register( + SRC_DIRS "." + INCLUDE_DIRS "." +) From 748d00968679b2fc13446079245d537914e2f58e Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Thu, 29 Aug 2024 11:28:20 -0300 Subject: [PATCH 05/12] feat(hw_cdc): create main.cpp Adds the minimum Arduino Sketch that will print "Hello World!" in the HW Serial USB CDC port. --- .../hw_cdc_hello_world/main/main.cpp | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 idf_component_examples/hw_cdc_hello_world/main/main.cpp diff --git a/idf_component_examples/hw_cdc_hello_world/main/main.cpp b/idf_component_examples/hw_cdc_hello_world/main/main.cpp new file mode 100644 index 00000000000..d7ac057cfdf --- /dev/null +++ b/idf_component_examples/hw_cdc_hello_world/main/main.cpp @@ -0,0 +1,10 @@ +#include + +void setup() { + Serial.begin(); // USB CDC doens't need a baud rate +} + +void loop() { + Serial.println("Hello world!"); + delay(1000); +} From 837f90419179910d371bb587af7d94cd0eab4e01 Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Thu, 29 Aug 2024 11:30:47 -0300 Subject: [PATCH 06/12] feat(hw_cdc): create idf_component.yml Adds necessary ESP32 Registry information in order to make ESP32 Arduino to be automatically included in the project as an IDF component. --- .../hw_cdc_hello_world/main/idf_component.yml | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 idf_component_examples/hw_cdc_hello_world/main/idf_component.yml diff --git a/idf_component_examples/hw_cdc_hello_world/main/idf_component.yml b/idf_component_examples/hw_cdc_hello_world/main/idf_component.yml new file mode 100644 index 00000000000..f955824767c --- /dev/null +++ b/idf_component_examples/hw_cdc_hello_world/main/idf_component.yml @@ -0,0 +1,6 @@ +## IDF Component Manager Manifest File +dependencies: + espressif/arduino-esp32: + version: "*" + override_path: "../../../" + pre_release: true From f949cd8a24b006743c260578a5e594a3231be0dd Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Thu, 29 Aug 2024 11:35:55 -0300 Subject: [PATCH 07/12] feat(hw_cdc): update main.cpp adds code to wait for the user to open the Serial Monitor --- idf_component_examples/hw_cdc_hello_world/main/main.cpp | 2 ++ 1 file changed, 2 insertions(+) diff --git a/idf_component_examples/hw_cdc_hello_world/main/main.cpp b/idf_component_examples/hw_cdc_hello_world/main/main.cpp index d7ac057cfdf..b4dfe230e6f 100644 --- a/idf_component_examples/hw_cdc_hello_world/main/main.cpp +++ b/idf_component_examples/hw_cdc_hello_world/main/main.cpp @@ -2,6 +2,8 @@ void setup() { Serial.begin(); // USB CDC doens't need a baud rate + while(!Serial) delay(100); // wait for the Serial Monitor to be open + Serial.println("\r\nStarting...\r\n"); } void loop() { From 95f95c57554cf1ff4f6d3cfd7957e87152040a4b Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Thu, 29 Aug 2024 11:37:30 -0300 Subject: [PATCH 08/12] feat(hw_cdc): formating text code Applying Code style and formating. --- .../hw_cdc_hello_world/main/main.cpp | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/idf_component_examples/hw_cdc_hello_world/main/main.cpp b/idf_component_examples/hw_cdc_hello_world/main/main.cpp index b4dfe230e6f..b5d543c9b9a 100644 --- a/idf_component_examples/hw_cdc_hello_world/main/main.cpp +++ b/idf_component_examples/hw_cdc_hello_world/main/main.cpp @@ -1,8 +1,14 @@ #include void setup() { - Serial.begin(); // USB CDC doens't need a baud rate - while(!Serial) delay(100); // wait for the Serial Monitor to be open + // USB CDC doens't need a baud rate + Serial.begin(); + + // wait for the Serial Monitor to be open + while(!Serial) { + delay(100); + } + Serial.println("\r\nStarting...\r\n"); } From 71ef98954016b5b7a456c1b7d3785ddb782498ce Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Fri, 30 Aug 2024 18:02:29 -0300 Subject: [PATCH 09/12] feat(hw_cdc): adds the example to idf_component.yml Adds the example to the list of example in the ESP32 Registry. --- idf_component.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/idf_component.yml b/idf_component.yml index 2f74301ea10..18742001118 100644 --- a/idf_component.yml +++ b/idf_component.yml @@ -96,3 +96,4 @@ dependencies: require: public examples: - path: ./idf_component_examples/hello_world + - path: ./idf_component_examples/hw_cdc_hello_world From f90f586492144a19772402ea05fffafb6af9096e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci-lite[bot]" <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Date: Sat, 31 Aug 2024 15:29:52 +0000 Subject: [PATCH 10/12] ci(pre-commit): Apply automatic fixes --- idf_component_examples/hw_cdc_hello_world/README.md | 4 ++-- idf_component_examples/hw_cdc_hello_world/main/main.cpp | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/idf_component_examples/hw_cdc_hello_world/README.md b/idf_component_examples/hw_cdc_hello_world/README.md index 8203a970d70..735dd516168 100644 --- a/idf_component_examples/hw_cdc_hello_world/README.md +++ b/idf_component_examples/hw_cdc_hello_world/README.md @@ -34,7 +34,7 @@ Below is the minimum list of files in the project folder. ``` ├── CMakeLists.txt Global project CMake configuration file ├── sdkconfig.defaults sdkconfig setting for an Arduino project -├── main +├── main │   ├── CMakeLists.txt Arduino sketch CMake configuration file │ ├── idf_component.yml List of IDF components necessary to build the project │   └── main.cpp Arduino Sketch code - don't forget to add "#include " on it @@ -60,4 +60,4 @@ list(APPEND compile_definitions "ARDUINO_USB_MODE=1") Those two lines will add a `-DSYMBOL=VAL` when compiling every source code file. -In order to make sure that it is actually working correctly, the [sketch](main/main.cpp) will execute `Serial.begin();` with no baudrate, which only works for USB CDC. +In order to make sure that it is actually working correctly, the [sketch](main/main.cpp) will execute `Serial.begin();` with no baudrate, which only works for USB CDC. diff --git a/idf_component_examples/hw_cdc_hello_world/main/main.cpp b/idf_component_examples/hw_cdc_hello_world/main/main.cpp index b5d543c9b9a..eb2bac1869c 100644 --- a/idf_component_examples/hw_cdc_hello_world/main/main.cpp +++ b/idf_component_examples/hw_cdc_hello_world/main/main.cpp @@ -3,12 +3,12 @@ void setup() { // USB CDC doens't need a baud rate Serial.begin(); - + // wait for the Serial Monitor to be open - while(!Serial) { + while (!Serial) { delay(100); } - + Serial.println("\r\nStarting...\r\n"); } From a6fdbaf51244dae1218b51b1e4293528e167549d Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Sun, 1 Sep 2024 16:00:40 -0300 Subject: [PATCH 11/12] fix(chw_cdc): typo fix Fixed Typo in the documentation. --- idf_component_examples/hw_cdc_hello_world/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/idf_component_examples/hw_cdc_hello_world/README.md b/idf_component_examples/hw_cdc_hello_world/README.md index 735dd516168..e4356d75ac3 100644 --- a/idf_component_examples/hw_cdc_hello_world/README.md +++ b/idf_component_examples/hw_cdc_hello_world/README.md @@ -3,7 +3,7 @@ # _HW Serial USB CDC example_ -This is the simplest buildable example made to be used as a template for new projects running Arduino-ESP32 as an ESP-IDF component that will redefine the `Serial` interface to be attached to the USB CDC Harware Serial port.\ +This is the simplest buildable example made to be used as a template for new projects running Arduino-ESP32 as an ESP-IDF component that will redefine the `Serial` interface to be attached to the USB CDC Hardware Serial port.\ See [arduino-esp32](https://components.espressif.com/components/espressif/arduino-esp32) in ESP Registry. ## How to use example From b835226cc11a4bbc35e80e7a458e8edda4eeef78 Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Sun, 1 Sep 2024 16:01:51 -0300 Subject: [PATCH 12/12] fix(hw_cdc): fixed a commentary typo Fixed commantary typo --- idf_component_examples/hw_cdc_hello_world/main/main.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/idf_component_examples/hw_cdc_hello_world/main/main.cpp b/idf_component_examples/hw_cdc_hello_world/main/main.cpp index eb2bac1869c..18718678430 100644 --- a/idf_component_examples/hw_cdc_hello_world/main/main.cpp +++ b/idf_component_examples/hw_cdc_hello_world/main/main.cpp @@ -1,7 +1,7 @@ #include void setup() { - // USB CDC doens't need a baud rate + // USB CDC doesn't need a baud rate Serial.begin(); // wait for the Serial Monitor to be open