Writing a Simple Project for Espressif IDF Command Line Compiler Tools

Today we're going to write a program that can compile, from the command line, with the Espressif IDF tools. (India-Delta-Foxtrot, not India-Delta-Echo) It's assumed that you have installed those tools already. If not, review the instructions online or in class.

You can follow along here in this blog post but also in a YouTube video for here:

So, the assumptions for this blog post are that:

1. The Espressif IDF tools are already installed (by you or the tech team)
   • If you need to install the tools on the Lassonde lab computers, check out this video:
     • Linux (Lab): https://youtu.be/2mqVCvINDH4
   • On a personal computer, with the IDE:
     • macOS: https://youtu.be/4cTu7rqkUuA, or
     • Windows: https://youtu.be/ae64DuJ8Rrs
2. You know how to use the terminal with basic commands like mkdir, cd, pwd, ls, etc.
3. You can edit these files with nano, vi, emacs or some other text editor in Linux (graphical or otherwise)

Make a folder inside examples called myproject and myproject it has subfolders main and build: the folders and files should look like this and assumes that your user name is username:

username
 └─examples
    └─myproject
       ├─CMakeLists.txt         [1st one]
       ├─main
       │  ├─CMakeLists.txt      [2nd one]
       │  ├─main.c
       │  └─sub3.s
       └─build
          └─[your executables will be here]

The first CMakeLists.txt file should be written as follows:

# The following 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)
# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
idf_build_set_property(MINIMAL_BUILD ON)
project(myproject)

Note that it's critical that you include the name of the folder, myproject, in the CMake file above. If you change the name of the folder then you need to change the name in the CMake file.

The second CMakeLists.txt file should be written in the main subdirectory as follows:

idf_component_register(SRCS "main.c" "sub3.s"
                       PRIV_REQUIRES spi_flash
                       INCLUDE_DIRS ".")

As with the first CMake file, you need to specify the exact names of the C and Assembler files, main.c and sub3.s. This is going to be a variation of the existing tutorial that you normally get in PDF format in class (but I'm changing it slightly so that if there is an issue and you need help from the TA then it'll hopefully make it clear where you're getting your information from). So, next you need to write your C file, main.c :

#include <stdio.h>
extern int sub3(int,int);
void app_main(void){
		int a = 3;
		int b = 1;
		int r = 0;
	
		r = sub3(a,b);
		printf("Subtraction result: %d\n",r); 
}

and your assembler file, sub3.s:

.global sub3
.text 

sub3:
	sub a0,a0,a1
	ret

Compile your Project

Once you have set up all your folders and files, head over to

username
 └─examples
    └─myproject

and type

espidf

This will allow for the Espressif IDF tools to be recognized. Then, once the IDF tools are recognized type

idf.py set-target esp32c3

and then

idf.py build

You should now have a set of executable files in your build folder (.bin and .elf files, with a companion .map file). Now flash your board using

idf.py -p /dev/ttyUSB0 flash

and monitor your output using

idf.py -p /dev/ttyUSB0 flash monitor

Testing on the Lassonde LAS 1006 computers

I ran the instructions above, in person, on one of the computer lab computers, as you can see below. It works.

Acknowledgments

Thank you to Profs. Kamen Kanev, Pooja Vashisth and Amir Amirsoleimani, as well as Mr. Jaspal Singh and Mr. Paul Griffith for their contributions to the course and our tools and getting me on track with all of it! Also thank you to our TAs, Hamid, Fatemeh and Umme and our awesome students for trying out the lab, finding issues with our instructions, fixing them and making the lab work! Well done everyone!

Updates

• March 16, 2026: added "Testing" section & footer.
• March 16, 2026: added the windows video.
• March 17, 2026: updated the line that said kespidf to espidf. This was based on feedback from students and TAs.
• March 18: idk to idf typo fixed (thanks class!)

---

James Andrew Smith is a Professional Engineer and Associate Professor in the Electrical Engineering and Computer Science Department of York University’s Lassonde School, with degrees in Electrical and Mechanical Engineering from the University of Alberta and McGill University.  Previously a program director in biomedical engineering, his research background spans robotics, locomotion, human birth, music and engineering education. While on sabbatical in 2018-19 with his wife and kids he lived in Strasbourg, France and he taught at the INSA Strasbourg and Hochschule Karlsruhe and wrote about his personal and professional perspectives.  James is a proponent of using social media to advocate for justice, equity, diversity and inclusion as well as evidence-based applications of research in the public sphere. You can find him on Twitter.  You can find him on BlueSky. Originally from Québec City, he now lives in Toronto, Canada.