ESP-IDF Basics: Your First Project with ESP32-C3 and Components
Table of Contents
Welcome to Espressif’s ESP-IDF Basics Workshop!
Introduction#
In this hands-on workshop, you’ll develop a solid understanding of the ESP-IDF framework, along with how to effectively use Visual Studio Code (VSCode) and Espressif’s official VSCode Extension. You’ll also gain practical experience working with ESP-IDF components.
In the first part, we’ll begin by verifying that your development environment is correctly set up, using the classic hello world example as our starting point. From there, we’ll walk through the structure of an ESP-IDF project, explore the build system, and set up a basic access point (SoftAP).
As we move to the second part, we’ll take a closer look at the network stack protocol and guide you through building a simple HTTP server.
The third part focuses on working with two commonly used peripherals, namely GPIO and I2C. We will explore the component system and the component registry, for using common libraries without worrying about managing dependencies or build system settings. After that, we’ll bring everything together to build a basic sensor gateway, combining networking and peripheral control into one cohesive project.
By the end of this session, you’ll have the foundational skills and confidence to start developing your own Espressif-based applications using ESP-IDF.
Agenda#
The workshop is divided into three parts, each lasting approximately one hour. Here’s the outline:
Part 1: Welcome and getting started
- Lecture 1 – ESP-IDF & VSCode Extension introduction
- Assignment 1.1 – Test ESP-IDF and VSCode installation by compiling and flashing the
hello_worldexample. Change the text of the example and check on the terminal. - Assignment 1.2 – Start a new project from the
blinkexample and check that the LED on the board is flashing.
Part 2: HTTP connectivity
- Lecture 2 – Connectivity layers, HTTP and MQTT, HTML, REST API
- Assignment 2.1 – Create an HTTP server which processes the request
GET /index.html/and returns<h1>Hello LED Control</h1>. - Assignment 2.2 – Add to the HTTP server the routes
GET /led/on→ turns the LED on and returns JSON {“led”: “on”}GET /led/off→ turns the LED off and returns JSON {“led”: “off”}POST /led/blink→ accepts JSON{ "times": int, "interval_ms": int }to blink the LED the specified number of times at the given interval, and returns JSON{"blink": "done"}
- Assignment 2.3 – (Optional) Add to the HTTP server the route
POST /led/flash→ accepts JSON{"periods": [int], "duty_cycles": [int]}and for each element, calculates the on-time and off-time and drives the LED accordingly.
Part 3: Peripherals and putting it all together
- Lecture 3 – GPIO, I2C and use of component registry. Reading the sensor.
- Assignment 3.1 – Create a new component to toggle the LED.
- Assignment 3.2 – Refactor previous code to use the component.
- Assignment 3.3 – Add component for reading the environment sensor onboard.
- Assignment 3.4 – (Optional) Add route:
GET /environment/→ returns a sensor reading. Choose the best json format for this task.
Prerequisites#
To follow this workshop, make sure you meet the prerequisites given below.
Basic knowledge#
- Basic electronics
- Resistors, capacitors, dc/dc supply
- Reading a schematic
- Basic embedded programming
- Flash memory
- Compile vs flash
- Basic knowledge of standard MCU peripherals, at least GPIO, and I2C.
- C programming language basics
- header files
- compiler / linker
definesstructs andtypedefs
- JSON and YAML format
- HTML and its main tags (
<html>,<body>,<h1>,<h2>,<p>) - Basic knowledge of HTTP request methods (
GET,POST) and the concept of URI and routes - Reference materials (distributed prior to workshop)
Required software#
- VSCode installed on your machine
- ESP-IDF extension added to your VSCode.
- ESP-IDF installed on your machine
You can install it via VSCode or using ESP-IDF installer manager
Required hardware#
- The ESP-C3-DevKit-RUST-2 (it will be provided at the workshop).
You could also use an ESP32-C3-Devkit board, but you would need to adjust gpio pin accordingly
Reference table#
| Prerequisite | Description | Reference |
|---|---|---|
| MCU memory types | Difference between Flash, RAM and EEPROM | L. Harvie (Medium) |
| MCU serial peripherals | Difference between SPI, I2C, UART | nextpcb.com |
| Header files and linker | What are headers file for and what’s the linker’s job | CBootCamp, themewaves |
| JSON | Language-independent data format derived from JavaScript. Backbone of REST APIs | Wikipedia |
| YAML | Human readable data serialization format used for dependency management through idf_component.yml | Wikipedia, datacamp.com |
| HTML tags | Basic HTML tags introduction | Freecodecamp |
| HTTP Request method | HTTP request (GET, POST, etc.) introduction and differences | Restfulapi.net |
| ESP-IDF VSCode Plugin | Espressif official VSCode Extension | vscode-esp-idf-extension installation |
Workshop#
Without further ado, let’s start! You can find a link to each workshop part below. Your next step is Lecture 1.
- Part 1
- Part 2
- Part 3
Conclusion#
Congratulations! You just arrived at the end of this workshop. We hope it was a fruitful experience and the start of a longer journey. Thank you for participating in Espressif’s 2025 Brazilian Summit workshop!
You are now able to create, build and flash new projects, use external libraries and components, create your own components, and control everything via an HTTP interface. You have now the basic foundation for an IoT application.
We hope this workshop has provided you with the foundational knowledge and confidence to start building your own Espressif-based applications. Keep experimenting, keep learning—and don’t forget to explore the rich ecosystem of tools and resources that Espressif offers.