Zephyr on ESP32-S3: Your First 'Hello World'

0. Introduction

Hello again!

In our first article, we built a clean, fully-controlled Zephyr RTOS development environment from scratch. Now it's time to put its power to the test with a more advanced microcontroller.

In this guide, we will use our new environment to build and flash a "Hello World" project onto a powerful ESP32-S3 (N16R8) development board. This board is a beast, featuring a dual-core processor, Wi-Fi, Bluetooth 5 (LE), and a massive 16MB of Flash and 8MB of PSRAM.

To do this, we will use a minimal, production-ready template that is pre-configured for a seamless experience in Visual Studio Code.

1. What You'll Need

Before we begin, make sure you have everything set up. The hardware is simple, and the software should already be configured if you followed our first guide.

Hardware:

• An ESP32-S3 development board (this guide uses a generic board with the N16R8 chip).
• A USB Type-C cable (make sure it's a data cable, not just for charging!).

Software:

• A fully configured Zephyr RTOS environment (Python, Git, West, SDK, etc.).
• Visual Studio Code with the recommended extensions (including C/C++, CMake Tools, and Task Explorer).

💡 Just starting out? If you haven't prepared your development environment yet, please follow my detailed guide first: Manual Zephyr RTOS Installation on Windows. This project template assumes your environment is ready to go.

2. Quick Start: From Zero to 'Hello World'

⚠️ Important: Make sure your Zephyr environment is activated! Run zephyr-env.cmd - your terminal should show (.venv) at the prompt.

2.1. Get the Project Template

Clone the repository to your local machine and open it in Visual Studio Code:

git clone https://github.com/gkiryaziev/Zephyr_ESP32S3-N16R8.git
cd Zephyr_ESP32S3-N16R8
code .

📦 Project Repository: https://github.com/gkiryaziev/Zephyr_ESP32S3-N16R8

2.2. Connect Your Hardware

Connecting the ESP32-S3 is as simple as it gets. Plug the USB-C cable into the board's USB-to-UART port (often labeled "UART" or "COM") and connect the other end to your computer.

2.3. Build the Project

We'll use VS Code tasks for a streamlined workflow. You have two options:

Option A: Command Palette

• Press Ctrl+Shift+B or go to Terminal → Run Task...
• Select Build from the dropdown

Option B: Task Explorer (recommended)

• Open the Task Explorer panel (side bar)
• Click the ▶️ play button next to the Build task

✅ Wait for the build to complete. You should see Build succeeded in the terminal.

2.4. Flash the Board

Run the Flash task using the same method (either Command Palette or Task Explorer). The board should be detected and flashed automatically.

2.5. Monitor the Output

Now, run the Monitor task. A serial monitor will open in your VS Code terminal.

2.6. Celebrate! 🎉

You should see the message Hello World! printing every second. You've just run your first Zephyr application on the ESP32-S3!

3. Under the Hood: What Makes This Template Smart

This template does more than just print text; it correctly configures the complex hardware of the ESP32-S3 for high performance.

3.1. Hardware Configuration (`esp32s3_devkitc.overlay`)

The overlay file is the heart of the hardware setup, telling Zephyr how to handle the massive 16MB Flash and 8MB PSRAM on this board.

/* 8MB PSRAM */
&psram0 {
  size = <DT_SIZE_M(8)>;
};

/* 16MB FLASH */
&flash0 {
  /delete-node/ partitions;
};

&flash0 {
  reg = <0x0 DT_SIZE_M(16)>;
};

#include <espressif/partitions_0x0_amp_16M.dtsi>

Key features:

• PSRAM Enabled: Explicitly sets the PSRAM size to 8MB.
• Flash Size Defined: Configures the flash memory to its full 16MB capacity.
• Partition Table: Includes a standard 16MB partition layout, essential for the ESP-IDF bootloader and firmware storage.

A Smarter Approach Than Command-Line Snippets

The world of ESP32 boards is diverse, with dozens of combinations of Flash and PSRAM sizes. To manage this complexity, Zephyr provides a powerful feature called Snippets.

Snippets are modular configuration files that you can apply at build time using the -S flag. For example, the standard Zephyr way to configure a board like ours would be to run a command like this:

west build -b esp32s3_devkitc -S flash-16M -S psram-8M

While this system is very flexible, it requires you to add these flags to every build command. This template simplifies the process by embedding the configuration for our 16MB Flash and 8MB PSRAM board directly into the .overlay file. This makes the build process cleaner and the VS Code Build task works perfectly out of the box.

Adapting the Template for Your Board

If your board has a different Flash/PSRAM configuration (e.g., 8MB Flash and 2MB PSRAM), you can easily switch to using snippets. Here's how:

1.Clear the Overlay File: Open the esp32s3_devkitc.overlay file and delete all its contents.

2. Activate Snippets in VS Code: Open the .vscode/tasks.json file. Inside the Build task, you will find these commented-out lines:

// "-S", "flash-16M",
// "-S", "psram-8M",

3. Uncomment and Configure: Uncomment those lines and change the values to match your hardware (e.g., "flash-8M", "psram-2M").

3.2. Project Configuration (prj.conf)

This file fine-tunes the kernel and drivers for optimal performance.

# PSRAM and FLASH
CONFIG_ESP_SPIRAM=y
CONFIG_SPIRAM_MODE_OCT=y
CONFIG_ESPTOOLPY_FLASHMODE_QIO=y
# Uncomment for higher performance
# CONFIG_SPIRAM_SPEED_80M=y
# CONFIG_ESPTOOLPY_FLASHFREQ_80M=y

• CONFIG_SPIRAM_MODE_OCT=y: Enables Octal SPI mode for PSRAM. This uses 8 data lines for blazing-fast access to external memory.
• CONFIG_ESPTOOLPY_FLASHMODE_QIO=y: Enables Quad I/O mode for the main flash. This uses 4 data lines to accelerate code execution.
• Optional 80MHz Mode: By default, the memory runs at 40MHz. For maximum performance, you can uncomment the last two lines to run both PSRAM and Flash at a speedy 80MHz.

3.3. The Application Code (src/main.c)

The code itself is a classic "Hello World" tailored for Zephyr.

#include <zephyr/kernel.h>
#include <zephyr/sys/printk.h>

int main(void)
{
  while (1) {
    printk("Hello World!\n");
    k_msleep(1000);
  }

  return 0;
}

Instead of toggling a pin, it uses printk() to send formatted strings to the serial console, a fundamental tool for debugging.

3.4. The VS Code Workflow

• tasks.json: Defines the Build, Flash, Monitor, and Clean scripts. The Build task is carefully crafted to explicitly point to the correct board target (esp32s3_devkitc/esp32s3/procpu) and our custom overlay files, ensuring a perfect build every time.
• c_cpp_properties.json: This file configures IntelliSense. Important: You must run the Build task at least once for code completion to work perfectly, as it relies on a compile_commands.json file generated during the build.

4. Troubleshooting Common Issues

❌ "west: command not found"

• Why: The Zephyr environment is not activated.
• Solution: Run your zephyr-env.cmd script (Windows) or source your environment file. Your prompt should show (.venv).

❌ "Flashing fails with 'a serial exception occurred' or 'Failed to connect'"

• Why: The board isn't in bootloader mode or the USB cable is faulty.
• Solution:

1. Ensure you are using a data-capable USB cable.

2. Manually enter bootloader mode: Press and hold BOOT, press and release RESET, then release BOOT. Run the Flash task again.

❌ "Gibberished or no output in the serial monitor"

• Why: Mismatched baud rate or a bad connection.
• Solution: The VS Code Monitor task handles the baud rate automatically (115200). Press the RESET button on your board. If that fails, re-check your USB cable and connection.

5. Conclusion

Congratulations! You've successfully built, flashed, and monitored your first Zephyr project on the powerful ESP32-S3.

This template provides a rock-solid foundation, handling the tricky memory configuration so you can focus on writing your application code. The integrated VS Code workflow makes the entire development process fast, efficient, and enjoyable.

Feel free to modify this template, experiment with the ESP32-S3's rich features, and build something amazing.

To be continued!