{"id":3864,"date":"2018-04-05T19:04:37","date_gmt":"2018-04-06T02:04:37","guid":{"rendered":"https:\/\/visualgdb.com\/w\/?p=3864"},"modified":"2025-10-14T20:28:09","modified_gmt":"2025-10-15T03:28:09","slug":"creating-and-referencing-custom-esp-idf-components","status":"publish","type":"post","link":"https:\/\/visualgdb.com\/tutorials\/esp32\/esp-idf\/components\/","title":{"rendered":"Creating and Referencing Custom ESP-IDF Components"},"content":{"rendered":"

This tutorial shows how to create custom ESP-IDF components and share them between your ESP32 projects. We will create a basic component\u00a0for running a simple PWM loop and will show how to reference it from 2\u00a0separate projects.<\/p>\n

Before you begin, install VisualGDB 5.4 or later.<\/p>\n

    \n
  1. Start Visual Studio and open the VisualGDB ESP-IDF project wizard:\"01-prj\"<\/a><\/li>\n
  2. On the first page select “Create a new\u00a0project based on a sample project”:\"02-newprj\"<\/a><\/li>\n
  3. Select your ESP32 toolchain and the ESP-IDF checkout you want to use:\"03-toolchain\"<\/a><\/li>\n
  4. Choose a sample project\u00a0that will be cloned when creating your project.\u00a0We will demonstrate the custom component based on the “blink” sample:
    \n    \"04-sample\"<\/a><\/li>\n
  5. Finally choose the debug method. In this tutorial we won’t be debugging the code, so\u00a0we can use a\u00a0serial port connection to\u00a0program the firmware into the FLASH memory without configuring JTAG:\"05-com\"<\/a><\/li>\n
  6. Press “Finish” to create the project and wait for it to load: \"06-files\"<\/a><\/li>\n
  7. All ESP-IDF projects consist of one or more components (i.e. static libraries) that are linked together to build the final executable. Most samples include only one component called “main”. For simplicity VisualGDB doesn’t show it as a separate component, but instead\u00a0displays its contents directly under the project node. Now we will add another component to the project. Right-click on the “Components” folder and select “Add->New Item”:
    \n<\/a>     \"07-newitem\"<\/a><\/li>\n
  8. Proceed with the default location, enter the component name and click “Add”:
    \n    \"08-pwm\"<\/a><\/li>\n
  9. VisualGDB will add the component files and will\u00a0start refreshing\u00a0the code model from the ESP-IDF. You won’t see the contents of the component until the refresh is complete:
    \n    \"09-loading\"<\/a>WARNING: if the project is configured with idf_build_set_property(MINIMAL_BUILD ON)<\/strong>, the new component will not appear in the list. You can disable that option by editing the main CMakeLists.txt file<\/strong>.<\/li>\n
  10. Once the code model is refreshed, the new component will be shown in\u00a0Solution Explorer similar to other components:\"10-files\"<\/a><\/li>\n
  11. Select the main .cpp file and press F2 to start renaming it. Then change the extension to “.c”:\"11-rename\"<\/a><\/li>\n
  12. Right-click on the component and select “Add->New File->C\/C++ Header file”.\u00a0 Append “\\PublicIncludes” to the location field:\"12-pubincl\"<\/a><\/li>\n
  13. Add the following code to the component:\n
    #pragma once\r\n\r\n#include \"driver\/gpio.h\"\r\n\r\n#ifdef __cplusplus\r\nextern \"C\"\r\n{\r\n#endif\r\n \r\n void RunGPIOCycle(gpio_num_t gpio, double dutyCycle);\r\n \r\n#ifdef __cplusplus\r\n}\r\n#endif<\/pre>\n
    Then select the “RunGPIOCycle” declaration, press Ctrl+. and select “Create implementation”:
    \n    \"13-makeimpl\"<\/a>VisualGDB will create an empty implementation\u00a0for the RunGPIOCycle() function, however it won’t automatically find the\u00a0“BasicPWM.h” header as the “PublicIncludes” directory is not yet\u00a0added to the include search path.<\/li>\n
  14. To fix that, we could add the header directory to either regular include directories (visible only for files inside the component) or exported directories (visible for all components in the same project). As the file will be included by the code that uses the component, add it to the exported directories:
    \n    \"14-sharedir\"<\/a>Note that the exported directories\u00a0must have relative paths. For your convenience you can select “<Edit…>” in the “Additional Include Directories” field and let VisualGDB compute the correct relative paths automatically:\"edit\"<\/a><\/li>\n
  15. Now you can\u00a0the implementation to the RunGPIOCycle() function:\n
    void RunGPIOCycle(gpio_num_t gpio, double dutyCycle)\r\n{\r\n    const int TotalCycles = 10000;\r\n    const int position = TotalCycles * dutyCycle;\r\n    gpio_set_level(gpio, 1);\r\n    for (int i = 0; i < position; i++)\r\n        asm(\"nop\");\r\n    gpio_set_level(gpio, 0);\r\n    for (int i = position; i < TotalCycles; i++)\r\n        asm(\"nop\");\r\n}<\/pre>\n
    \"15-pwm\"<\/a><\/li>\n
  16. Modify the blink_task() function in the main source file to call the RunGPIOCycle() function:\n
    #include \"BasicPWM.h\"\r\n#include <math.h>\r\n\r\nvoid blink_task(void *pvParameter)\r\n{\r\n    gpio_pad_select_gpio(BLINK_GPIO);\r\n    \/* Set the GPIO as a push\/pull output *\/\r\n    gpio_set_direction(BLINK_GPIO, GPIO_MODE_OUTPUT);\r\n \r\n    for (double i = 0; ; i += 0.005)\r\n        RunGPIOCycle(BLINK_GPIO, (sin(i) + 1) \/ 2);\r\n}<\/pre>\n
    \"16-call\"<\/a><\/li>\n
  17. Build the project and select “Debug->Program and\u00a0Start Without Debugging” to program it to the FLASH memory:\"17-program\"<\/a>Ensure that the on-board LED gradually turns on and off\u00a0as the PWM duty cycle goes from 0 to 100% and back to 0.<\/li>\n
  18. You can change the\u00a0GPIO number of the LED via VisualGDB Project Properties -> ESP-IDF Project -> ESP-IDF Configuration -> Blink GPIO Number:\"gpio\"<\/a><\/li>\n
  19. Now we will show how to import the component from another project.\u00a0Create another\u00a0project in a separate solution using the VisualGDB ESP-IDF\u00a0project wizard:\"18-prj2\"<\/a><\/li>\n
  20. Click on the “Components”\u00a0node\u00a0and select “Add->Existing Item”:
    \n    \"19-addcomp\"<\/a><\/li>\n
  21. Then locate the component.mk file of the BasicPWM component:\"20-locatemak\"<\/a><\/li>\n
  22. See how VisualGDB automatically updates the project’s Makefile to include the new component:\"21-relpath\"<\/a><\/li>\n
  23. You can now use the component exactly the same way as you did in the first project – include the <BasicPWM.h> file and call the RunGPIOCycle() function. ESP-IDF will automatically\u00a0use\u00a0the correct include paths and will link the component with the final project:\"22-imported\"<\/a>You can also store your components outside the project directories. Simply pick an arbitrary location when creating a new component and VisualGDB will place it there, updating all necessary Makefiles.<\/li>\n<\/ol>\n","protected":false},"excerpt":{"rendered":"
    This tutorial shows how to create custom ESP-IDF components and share them between your ESP32 projects. We will create a<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[142],"tags":[160,138,79],"_links":{"self":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/3864"}],"collection":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/comments?post=3864"}],"version-history":[{"count":2,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/3864\/revisions"}],"predecessor-version":[{"id":9077,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/3864\/revisions\/9077"}],"wp:attachment":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/media?parent=3864"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/categories?post=3864"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/tags?post=3864"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}