Zephyr RTOS on ESP32: Complete Beginner's Guide

From Zero to Hello World on Ubuntu Linux

#

Written for absolute beginners. Every error encountered, every fix applied , documented step by step. Tested on: Ubuntu 24.04 | ESP32 DevKitC | Zephyr v4.2.0 | SDK 0.17.0

What is Zephyr?

#

Zephyr is a real-time operating system (RTOS) for embedded devices - think microcontrollers, IoT sensors, smart devices. It is developed under the Linux Foundation and is used in professional embedded systems worldwide.

Why learn Zephyr as a beginner?

#

Zephyr is the perfect training ground before diving into Linux kernel development.

What You Need

#

• A laptop/PC running Ubuntu (20.04, 22.04, or 24.04)
• An ESP32 DevKitC board (the black board with WiFi+BT)
• A micro-USB cable
• Internet connection
• ~10GB of free disk space

⚠️ Check disk space first! Zephyr + SDK needs ~8GB.

df -h /

You need at least 10GB free in the Avail column.

Step 1 - Install System Dependencies

#

Open a terminal and run:

sudo apt update
sudo apt install --no-install-recommends \
  git cmake ninja-build gperf \
  ccache dfu-util device-tree-compiler wget \
  python3-dev python3-pip python3-setuptools \
  python3-tk python3-wheel \
  xz-utils file make gcc gcc-multilib \
  g++-multilib libsdl2-dev libmagic1

This takes 3–5 minutes depending on your connection.

Verify

#

cmake --version   # Should show 3.x.x
python3 --version # Should show 3.x.x
git --version     # Should show 2.x.x

Step 2 - Install West

#

West is Zephyr’s meta-tool for managing source code, building, and flashing. Install it using pipx (the modern, clean way):

sudo apt install pipx
pipx install west
pipx ensurepath
source ~/.zshrc   # or: source ~/.bashrc  (if you use bash)

Verify

#

west --version
# Expected output: west, version 1.5.0 (or similar)

💡 Why pipx and not pip? pipx installs tools in isolated environments, preventing conflicts with other Python packages on your system.

Step 3 - Download Zephyr Source

#

cd ~
west init zephyrproject
cd zephyrproject
west update

⚠️ west update takes 10–20 minutes. It downloads the entire Zephyr source tree (~2GB). Just let it run.

What these commands do

#

• west init - creates the zephyrproject folder and fetches the manifest
• west update - downloads all the Zephyr modules defined in the manifest

Step 4 - Set Up Python Virtual Environment

#

Zephyr’s build scripts need specific Python packages. We use a virtual environment to keep things clean:

cd ~
python3 -m venv zephyr-env
source ~/zephyr-env/bin/activate
pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

You should now see (zephyr-env) at the start of your terminal prompt.

⚠️ Important: You need to activate the venv every time you open a new terminal:

source ~/zephyr-env/bin/activate

Inject required packages into West’s Python environment

#

West uses its own Python (via pipx), separate from your venv. Inject these packages:

pipx inject west pyserial intelhex pyelftools cmake

💡 These are needed for flashing and building - you’ll get errors without them (see Errors Reference).

Step 5 - Download and Install Zephyr SDK

#

The Zephyr SDK contains compilers and tools for all supported architectures, including Xtensa (ESP32).

cd ~
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.17.0/zephyr-sdk-0.17.0_linux-x86_64.tar.xz
tar xf zephyr-sdk-0.17.0_linux-x86_64.tar.xz
cd zephyr-sdk-0.17.0
./setup.sh

When setup.sh asks questions:

• Install host tools? → type y and press Enter
• Register Zephyr SDK CMake package? → type y and press Enter

The download is ~1.6GB and takes 5–10 minutes.

Set the SDK path (required for building)

#

export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.17.0

⚠️ Add this to your ~/.zshrc or ~/.bashrc so you don’t need to run it every time:

echo 'export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.17.0' >> ~/.zshrc

Switch Zephyr to a stable version compatible with SDK 0.17.0

#

The latest Zephyr (main branch) requires SDK 1.0+. Switch to the stable v4.2.0 release:

cd ~/zephyrproject/zephyr
git checkout v4.2.0
west update

Step 6 - Build Hello World

#

Now let’s compile the Hello World sample for the ESP32:

source ~/zephyr-env/bin/activate
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.17.0
cd ~/zephyrproject/zephyr
west build -p always -b esp32_devkitc/esp32/procpu samples/hello_world

What each flag means

#

Success looks like

#

[211/211] Linking C executable zephyr/zephyr.elf
Memory region   Used Size  Region Size  %age Used
FLASH:         144440 B   4194048 B     3.44%
...
Successfully created esp32 image.

Step 7 - Flash to ESP32

#

First, fix USB permissions (required on Ubuntu, only needed once):

sudo usermod -a -G dialout $USER
# Log out and back in for this to take effect
# OR use this temporary fix:
sudo chmod 666 /dev/ttyACM0

Then flash:

west flash --esp-device /dev/ttyACM0

💡 If your device appears as /dev/ttyUSB0 instead, use that:

west flash --esp-device /dev/ttyUSB0

💡 Find your device port:

ls /dev/tty* | grep -E "ACM|USB"

💡 If upload fails, hold the BOOT button on your ESP32 while flashing.

Step 8 - View Output

#

Open the serial monitor to see your program’s output:

west espressif monitor --port /dev/ttyACM0

You should see

#

*** Booting Zephyr OS build v4.2.0 ***
Hello World! esp32_devkitc/esp32/procpu

You are now running Zephyr RTOS on your ESP32.

Press Ctrl+] to exit the serial monitor.

❌ Errors & Fixes Reference

#

Every error encountered during this setup, and exactly how to fix each one.

❌ Error: No space left on device

#

fatal: write error: No space left on device

Cause: Your disk is full.

Fix:

df -h /                          # Check available space
du -sh ~/* | sort -rh | head -10 # Find what's using space

Free up space before continuing. Zephyr needs ~8GB.

❌ Error: dlopen(): error loading libfuse.so.2

#

AppImages require FUSE to run.

Cause: FUSE library missing (needed for AppImage format).

Fix:

sudo apt install libfuse2

❌ Error: source: no such file or directory: /home/.../zephyr-env/bin/activate

#

Cause: The virtual environment wasn’t created yet, or you’re in the wrong directory.

Fix:

cd ~
python3 -m venv zephyr-env
source ~/zephyr-env/bin/activate

❌ Error: Missing jsonschema dependency (CMake)

#

CMake Error: Missing jsonschema dependency

Cause: West uses its own Python environment (via pipx) which doesn’t have jsonschema.

Fix:

pipx inject west jsonschema

❌ Error: No board named 'esp32_devkitc_wroom' found

#

No board named 'esp32_devkitc_wroom' found. Did you mean:
  esp32_devkitc
  esp32s3_devkitc

Cause: Wrong board name used.

Fix: Use the correct board target:

west build -p always -b esp32_devkitc/esp32/procpu samples/hello_world

❌ Error: Board qualifiers 'esp32' for board 'esp32_devkitc' not found

#

Valid board targets for esp32_devkitc are:
  esp32_devkitc/esp32/procpu
  esp32_devkitc/esp32/appcpu

Cause: Need to specify the full board target with qualifiers.

Fix:

west build -p always -b esp32_devkitc/esp32/procpu samples/hello_world

❌ Error: Could not find Zephyr-sdk compatible with version "1.0"

#

Could not find a configuration file for package "Zephyr-sdk"
compatible with requested version "1.0".

Cause: You’re on the bleeding-edge main branch of Zephyr which requires SDK 1.0, but SDK 0.17.0 is installed.

Fix: Switch to the stable Zephyr release:

cd ~/zephyrproject/zephyr
git checkout v4.2.0
west update
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.17.0

❌ Error: ModuleNotFoundError: No module named 'elftools'

#

ModuleNotFoundError: No module named 'elftools'

Cause: pyelftools not installed in West’s Python environment.

Fix:

pipx inject west pyelftools

❌ Error: ModuleNotFoundError: No module named 'intelhex'

#

ModuleNotFoundError: No module named 'intelhex'

Cause: intelhex not installed in West’s Python environment.

Fix:

pipx inject west intelhex

❌ Error: ModuleNotFoundError: No module named 'serial'

#

Pyserial is not installed. ModuleNotFoundError: No module named 'serial'

Cause: pyserial not installed in West’s Python environment.

Fix:

pipx inject west pyserial

💡 Pro tip: Install all commonly missing modules at once to avoid hitting these one by one:

pipx inject west pyserial intelhex pyelftools cmake

❌ Error: Path '/dev/ttyACM0' is not readable

#

Invalid value for '--port' / '-p': Path '/dev/ttyACM0' is not readable.

Cause: Your user doesn’t have permission to access the USB serial port.

Fix (temporary):

sudo chmod 666 /dev/ttyACM0

Fix (permanent):

sudo usermod -a -G dialout $USER
# Then log out and back in

❌ Error: Blinky sample fails - undeclared __device_dts_ord

#

error: '__device_dts_ord_DT_N_ALIAS_led0_P_gpios_IDX_0_PH_ORD' undeclared

Cause: The ESP32 DevKitC board definition in Zephyr doesn’t have an LED alias in its device tree. The blinky sample requires an led0 alias to be defined.

Status: This is a known gap and a potential first contribution to the Zephyr project.

Workaround: Use hello_world sample instead:

west build -p always -b esp32_devkitc/esp32/procpu samples/hello_world

Proper fix (contribution opportunity): Add an LED definition to the board’s .dts file at:

~/zephyrproject/zephyr/boards/espressif/esp32_devkitc/esp32_devkitc_procpu.dts

Daily Workflow Cheatsheet

#

Every time you open a new terminal to work with Zephyr:

# 1. Activate Python environment
source ~/zephyr-env/bin/activate

# 2. Set SDK path
export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.17.0

# 3. Go to Zephyr directory
cd ~/zephyrproject/zephyr

# 4. Build
west build -p always -b esp32_devkitc/esp32/procpu samples/hello_world

# 5. Fix USB permission (if needed)
sudo chmod 666 /dev/ttyACM0

# 6. Flash
west flash --esp-device /dev/ttyACM0

# 7. Monitor
west espressif monitor --port /dev/ttyACM0

💡 Save time: Add steps 1 and 2 to your ~/.zshrc so they run automatically:

echo 'source ~/zephyr-env/bin/activate' >> ~/.zshrc
echo 'export ZEPHYR_SDK_INSTALL_DIR=~/zephyr-sdk-0.17.0' >> ~/.zshrc

Next Steps

#

Now that your environment is working, here’s a learning path toward contributing to Zephyr and eventually Linux kernel development:

Beginner (Now)

#

• Explore other samples in ~/zephyrproject/zephyr/samples/
• Read Zephyr’s Getting Started Guide
• Join Zephyr’s Discord

Intermediate (1–3 months)

#

• Understand Device Tree - edit a .dts file
• Fix the LED alias issue on ESP32 DevKitC (first contribution!)
• Look for Good First Issues on GitHub

Advanced (3–6 months)

#

• Write a simple Zephyr driver
• Submit a pull request to Zephyr upstream
• Explore Linux kernel modules on Raspberry Pi

Expert (6–12 months)

#

• Apply for GSoC 2027 with the Linux Foundation / Zephyr project
• Contribute to Linux kernel via git send-email

Useful Resources

#

Guide written on March 18, 2026 - based on real setup session from scratch on Ubuntu 24.04