Chapter 0: ESP-IDF Toolchain and OSRCORE Hardware

0.1 Key Points

• ESP-IDF installation methods: official scripts and the VS Code extension
• ESP-IDF project structure and the role of CMakeLists.txt
• Common idf.py commands: build, flash, monitor, and menuconfig
• OSRCORE peripheral and GPIO resource overview
• USB CDC console configuration through USB Serial/JTAG

0.2 Course Content

This chapter explains how to set up the ESP-IDF development environment on Linux, macOS, and Windows, then introduces the hardware resources of the OSRCORE board. After this chapter, you should be able to build, flash, and monitor a minimal ESP-IDF application.

OSRCORE is a compact mobile-robot control board based on the ESP32-S3 dual-core 240 MHz MCU. It integrates a WS2812B RGB LED, a passive buzzer, a QMI8658 six-axis IMU, a quadrature encoder interface, SBUS receiver input, ESC and servo PWM outputs, battery voltage sensing, and a USB CDC debug console. These peripherals cover the basic requirements of a small wheeled robot.

0.3 Basic Learning

ESP-IDF Installation

The recommended installation method is the official script:

# Linux / macOS
git clone --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf
cd ~/esp/esp-idf
./install.sh esp32s3
. ./export.sh          # Run this every time a new terminal is opened

On Windows, install ESP-IDF using the official Windows Installer and run commands in the ESP-IDF CMD terminal.

Project Structure

my_project/
├── CMakeLists.txt          # Top level: cmake_minimum_required + project()
├── sdkconfig.defaults      # Default menuconfig options
└── main/
    ├── CMakeLists.txt      # idf_component_register(SRCS "main.c")
    └── main.c

A minimal top-level CMakeLists.txt looks like this:

cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_project)

Common idf.py Commands

Command	Description
idf.py set-target esp32s3	Set the target chip. Required for the first build.
idf.py menuconfig	Open the configuration menu.
idf.py build	Build the project.
idf.py flash	Flash the firmware to the board.
idf.py monitor	Open the serial monitor.
idf.py flash monitor	Flash and then immediately monitor.
idf.py fullclean	Remove all build artifacts.

Specify the serial port when needed:

idf.py -p /dev/ttyACM0 flash monitor

OSRCORE Hardware Resource Overview

Peripheral	GPIO	Driver / Protocol	Notes
WS2812B LED	GPIO45	RMT TX	GRB byte order
Passive buzzer	GPIO42	LEDC TIMER1 CH2	10-bit, 50% duty
ESC throttle	GPIO1	LEDC TIMER0 CH0	50 Hz, 14-bit
Steering servo	GPIO2	LEDC TIMER0 CH1	50 Hz, 14-bit
Encoder EA	GPIO3	PCNT edge	512 PPR
Encoder EB	GPIO9	PCNT level	Gear ratio 10.55
I2C SDA	GPIO10	I2C_NUM_0	400 kHz
I2C SCL	GPIO11	I2C_NUM_0	400 kHz
QMI8658 IMU	I2C 0x6B	I2C	±8g / ±2048 dps
SBUS RX	GPIO44	UART0	100k, 8E2, inverted
Battery ADC	GPIO4	ADC1 CH3	Voltage divider
Battery enable	GPIO16	GPIO output	Active high
USB CDC	Internal	USB Serial/JTAG	Console

USB CDC Console Configuration

Add the following to sdkconfig.defaults:

CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y
CONFIG_ESP_CONSOLE_SECONDARY_NONE=y

Or initialize USB Serial/JTAG in code:

usb_serial_jtag_driver_config_t cfg = {
    .rx_buffer_size = 256,
    .tx_buffer_size = 256,
};
usb_serial_jtag_driver_install(&cfg);
esp_vfs_usb_serial_jtag_use_driver();

0.4 Program Study

The entry point of an ESP-IDF application is app_main(). It runs in a FreeRTOS task. A minimal OSRCORE application is:

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"

static const char *TAG = "main";

void app_main(void)
{
    ESP_LOGI(TAG, "Hello OSRCORE!");
    while (1) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

ESP_LOGI prints a timestamped log line with a tag. Log levels are ordered as LOGV < LOGD < LOGI < LOGW < LOGE.

0.5 Summary

This chapter covered ESP-IDF installation, the basic idf.py workflow, and the OSRCORE hardware resource map. The following chapters focus on one peripheral at a time and gradually build a complete robot control system.

---