From ab965c5226eeafe45a9bccbb98b9d70058f52da0 Mon Sep 17 00:00:00 2001 From: Ricardo Tafas Date: Wed, 24 Sep 2025 08:27:35 +0200 Subject: [PATCH] Rewritting the Zephyr First Steps tutorial, adding it to a proper folder location. --- .../featured.webp} | Bin .../img/zephyr-2.webp | Bin .../zephyr-rtos-on-esp32-first-steps/index.md | 131 ++++++++ .../zephyr-rtos-on-esp32-first-steps/index.md | 286 ------------------ 4 files changed, 131 insertions(+), 286 deletions(-) rename content/blog/{zephyr-rtos-on-esp32-first-steps/img/zephyr-1.webp => 2021/02/zephyr-rtos-on-esp32-first-steps/featured.webp} (100%) rename content/blog/{ => 2021/02}/zephyr-rtos-on-esp32-first-steps/img/zephyr-2.webp (100%) create mode 100644 content/blog/2021/02/zephyr-rtos-on-esp32-first-steps/index.md delete mode 100644 content/blog/zephyr-rtos-on-esp32-first-steps/index.md diff --git a/content/blog/zephyr-rtos-on-esp32-first-steps/img/zephyr-1.webp b/content/blog/2021/02/zephyr-rtos-on-esp32-first-steps/featured.webp similarity index 100% rename from content/blog/zephyr-rtos-on-esp32-first-steps/img/zephyr-1.webp rename to content/blog/2021/02/zephyr-rtos-on-esp32-first-steps/featured.webp diff --git a/content/blog/zephyr-rtos-on-esp32-first-steps/img/zephyr-2.webp b/content/blog/2021/02/zephyr-rtos-on-esp32-first-steps/img/zephyr-2.webp similarity index 100% rename from content/blog/zephyr-rtos-on-esp32-first-steps/img/zephyr-2.webp rename to content/blog/2021/02/zephyr-rtos-on-esp32-first-steps/img/zephyr-2.webp diff --git a/content/blog/2021/02/zephyr-rtos-on-esp32-first-steps/index.md b/content/blog/2021/02/zephyr-rtos-on-esp32-first-steps/index.md new file mode 100644 index 000000000..2c356216d --- /dev/null +++ b/content/blog/2021/02/zephyr-rtos-on-esp32-first-steps/index.md @@ -0,0 +1,131 @@ +--- +title: "Zephyr RTOS on ESP32 — First Steps" +date: 2021-02-24 +lastmod: 2025-09-26 +showAuthor: false +authors: + - ricardo-tafas +tags: + - Esp32 + - Zephyr + - Embedded Systems + - Espressif +summary: "First Steps with Zephyr on ESP32, a collection of all needed tutorials." +--- + +## General Information + +- This is a Quick Start based on several guidelines. +- There are many tutorials listed in this page, all of them very important for a sucessful start. +- It is common to overstep and miss important details. **Be attentive.** + +## Before Starting + +- Zephyr is an RTOS maintained by the Linux Foundation and ported to several architectures. [More about Zephyr.](https://www.zephyrproject.org) +- Espressif officially supports Zephyr RTOS on its devices. [Visit the Product page](https://www.espressif.com/en/sdks/esp-zephyr). +- Check if your device is supported. Users can track the development status of Zephyr on Espressif devices by following the [Support Status Page](https://developer.espressif.com/software/zephyr-support-status/). + +## Installation + +- Follow the [Official Getting Started Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html) +- Make sure your system is updated. +- Follow the instructions with attention to every step. +- Extra precautions are needed with Windows: + - Paths on environment variables may have problems with mixing '\\' and '/'. + - You must to use Chocolatey, otherwise installation is complex. If Chocolatey is blocked, refer this article, as this step is mandatory. + +## First Build + +- The application *west* is the meta tool of Zephyr. After following the *Getting Started Guide*, only *west* will be needed. +- Simpleboot is the name used for the *absence* of a second stage bootloader. It is the old school firmware build. +- Find your board. + - [Boards search page](https://docs.zephyrproject.org/latest/boards/index.html). *Vendor* refers to the board manufacturer. Many different vendors, including Espressif itself, use Espressif chips. + - [Boards Folder in Github](https://github.com/zephyrproject-rtos/zephyr/tree/main/boards). +- If your board is not listed or if you are using a custom board, try using a regular DevkitC for the Espressif device you have. It won't change outcome for now. +- Read the Board documentation, and stop after fetching the binary blobs. **There are important information and commands that cannot be missed.** +- [Jump to Manual Build](https://docs.zephyrproject.org/latest/boards/espressif/esp32c3_devkitc/doc/index.html#manual-build) and execute all the steps. +- If all went well, you should have seen the *hello world* message. +- Use ```Ctrl + ]``` to exit the console application. You can study the Monitor manual [here](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/tools/idf-monitor.html). + +{{< alert icon="circle-info" cardColor="#b3e0f2" iconColor="#04a5e5">}} +- All Espressif boards will require to fetch binary blobs. +{{< /alert >}} +\ +{{< alert >}} +Some devkits have 2 options for console output: +- UART0 (usually with on-board Serial-USB converter), as default. +- USB, using the On-Chip USB-Serial converter. + +If you see some messages but not the *hello world* message, for now, try connecting to the other port. +{{< /alert >}} + +## Build with Zephyr Port of MCUboot + +- If you saw the *hello world*, everything is good so far. +- If OTA or any form of firmware ugrade is necessary, MCUboot will be mandatory, so we test it. The same applies to Security. [More about MCUboot](https://docs.mcuboot.com/). +- There are 2 options for MCUboot: Zephyr port or Espressif port. + - Zephyr port: software security only. + - Espressif Port: hardware backed security. +- Let's go with the Zephyr Port for now. +- First, enable MCUboot. [Instructions here](https://docs.zephyrproject.org/latest/boards/espressif/esp32c3_devkitc/doc/index.html#mcuboot-bootloader). Further explanation: + - Zephyr project configuration is based on Kconfigs. [More about it here](https://docs.zephyrproject.org/latest/build/kconfig/index.html). + - You can [search](https://docs.zephyrproject.org/latest/kconfig.html) for Kconfigs. + - All project configurations go to a file named *proj.conf*. On the instructions above, you will have to edit the file ```zephyr/samples/hello_world/proj.conf```. +- It is time to build the MCUboot and Zephyr. [Instructions here](https://docs.zephyrproject.org/latest/boards/espressif/esp32c3_devkitc/doc/index.html#sysbuild). + - The ```--sysbuild``` option commands *west* to build the Zephyr, but also to build the MCUboot Second Stage Bootloader. + - The building process results in 2 binaries, but you don't have to worry, *west* takes care of flashing both correctly. +- Remember to flash the device and start the monitor, just like the manual build. +- You should see, during the boot message, that MCUboot was executed. +- You should also see the *hello world* message. + +## Building the Espressif Port of MCUboot + +- If all went fine so far, it is time to build the Espressif Port of MCUboot. This allows for features like Flash Encryption and Secure Boot, although we won't be enabling them now. +- Clone the MCUboot repository on a different folder than Zephyr. +``` +git clone https://github.com/mcu-tools/mcuboot.git +``` +- Follow [the MCUboot instructions](https://docs.mcuboot.com/readme-espressif.html) and make sure you don't skip any step. + - If using Windows, make sure all paths are correct. + - Make sure NINJA is working properly. Having errors of any kind is a bad sign. + - Stop at the ninja flashing command. +- Now, the Zephyr image needs to be rebuilt to workwith MCUboot - Espressif Port. This is not automatic. + - The Kconfig option enabling MCUboot must be kept, so Zephyr is built accordingly. + - There is no need to build MCUboot, as it as already done with the steps above and flashed to the device. + - Only Zephyr needs to be built. This is done by building it without using the ```--sysbuild``` option, similar to the Manual build. +``` +west build -b samples/hello_world -p +``` +- The ```-p``` option commands *west* to do a pristine build, which is a build after a clean-up. It is recomended when there are big config changes. +- Flash it and make it run. Usual commands: +``` +west flash +west espressif monitor +``` +- If you saw the bootloader running MCUboot and the *hello world* message, everything went fine. There is no noticeable difference from the Zephyr port of MCUboot. + +## Next Steps + +{{< alert icon="circle-info" cardColor="#b3e0f2" iconColor="#04a5e5">}} +The steps above are valid for all examples. But be careful, some samples may not work directly out of the box. +{{< /alert >}} + +- From this point and forward, you will face more *Zephyr Problems* than *Espressif Problems*. +- Run the Blinking example. It will not work directly on DevkitC, because it has no LED. You will need to learn about OVERLAYS, and have a breadboard to add LED circuitry, if not is present. +- Test Wi-Fi examples (if present). + - It's recommeded to use Wi-Fi Shell at first. +- Test BlueTooth Examples (if present) +- Test 15.4 (if present) +- Test OTA with MCUboot + +## Selected Tutorials + +In case you need more information or detailed explanations, there are lots of sources to look for. These 2 below are very friendly for beginners: + +- Shawn Hymel and Digikey have a very nice series about Zephyr. [Introduction to Zephyr](https://www.youtube.com/watch?v=mTJ_vKlMS_4) +- The Pull-Up Resistor Channel also has good tutorials. [ESP32 on Zephyr OS](https://www.youtube.com/watch?v=Z_7y_4O7yTw) + +Make sure to see all the videos on those series. There may be changes regarding commands due to Zephyr evolution. If any command is not working, check the official documentation or ask Discord. + +--- +The [original article](https://medium.com/the-esp-journal/zephyr-rtos-on-esp32-first-steps-2185c0d56250) was published on Medium, at the [ESP Journal](https://medium.com/the-esp-journal). It was rewritten for the current format. diff --git a/content/blog/zephyr-rtos-on-esp32-first-steps/index.md b/content/blog/zephyr-rtos-on-esp32-first-steps/index.md deleted file mode 100644 index 96b59c387..000000000 --- a/content/blog/zephyr-rtos-on-esp32-first-steps/index.md +++ /dev/null @@ -1,286 +0,0 @@ ---- -title: "Zephyr RTOS on ESP32 — First Steps" -date: 2021-02-24 -showAuthor: false -featureAsset: "img/featured/featured-espressif.webp" -authors: - - glauber-ferreira -tags: - - Esp32 - - Zephyrrtos - - Zephyr - - Embedded Systems - - Espressif - ---- -{{< figure - default=true - src="img/zephyr-1.webp" - >}} - ->__Note:__ This article has been reviewd to reflect the latest Zephyr features as of Q4 2024. - -Zephyr is a very low footprint RTOS maintained by the Linux Foundation and ported to several architectures. This RTOS has been gaining massive support from many silicon manufacturers and an ever-growing list of contributors on its mainline. - -Espressif has been expanding support for Zephyr RTOS on ESP32, an extremely popular SoC among hobbyists but also widely used in commercial applications. Since its release, this SoC became famous for integrating both Wifi and Bluetooth stacks on a single chip and for being very cost-competitive. In this post, all the required steps to prepare your host’s environment to use Zephyr on ESP32 will be explained. In the end, we will run a __hello world__ application to validate our setup. In this step-by-step guide, the __ESP32 DevKitC_WROVER__ board will be used. - -{{< figure - default=true - src="img/zephyr-2.webp" - >}} - -The first thing to do is to prepare Zephyr’s development environment. I briefly list the steps required for Linux (Ubuntu 22.04.1 LTS), for the most up-to-date documentation, and for support for other Operating Systems you can see Zephyr’s official [Getting Started](https://docs.zephyrproject.org/latest/develop/getting_started/index.html) guide and, specifically, you can see most of the original instructions included in this post in the [ESP32 SoC section](https://docs.zephyrproject.org/latest/boards/espressif/index.html) of the Zephyr Project documentation. - -## Updating Linux - -Before we start, update your repositories list. - -```sh -sudo apt update -sudo apt upgrade -``` - -## Installing dependencies - -Run __apt__ to install dependencies: - -```sh -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 -``` - -Verify the versions of the main dependencie: - -```sh -cmake --version -python3 --version -dtc --versio -``` - -The current minimum required versions for this tools are: - -- CMake: 3.20.5 -- Python: 3.10 -- Devicetree compiler: 1.4.6 - -## Getting Zephyr and installing Python dependencies - -Install __west__ and ensure that __~/.local/bin__ is part of your __PATH__ environment variable: - -```sh -pip3 install -- user -U west -echo ‘export PATH=~/.local/bin:”$PATH”’ >> ~/.bashrc -source ~/.bashrc -``` - -Here is a worthy observation: west is the tool that manages the entire life-cycle of a Zephyr-based project. This is made clearer below. Now, get Zephyr’s source code: - -```sh -west init ~/zephyrproject -cd ~/zephyrproject -west update -``` - -Be patient, these last commands will fetch Zephyr’s repository and all the HALs (including Espressif’s) already ported to this RTOS. Note that we do not explicitly call a git command to clone the repositories, __west__ takes care of everything. - -Zephyr’s __requirements.txt__ file declares additional Python dependencies. Install them through pip3. - -```sh -pip3 install --user -r \ -~/zephyrproject/zephyr/scripts/requirements.txt -``` - -## Installing Zephyr’s toolchain - -Zephyr’s SDK adds several additional tools for the host. Download and verify the Zephyr SDK bundle: - -> __Note:__ -> You can change `0.16.8` to another version in the instructions below if needed; the [Zephyr SDK Releases](https://github.com/zephyrproject-rtos/sdk-ng/tags) page contains all available SDK releases. - -```sh -cd ~ -wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.8/zephyr-sdk-0.16.8_linux-x86_64.tar.xz -wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.8/sha256.sum | shasum --check --ignore-missing -``` -Extract the Zephyr SDK bundle archive: - -```sh -tar xvf zephyr-sdk-0.16.8_linux-x86_64.tar.xz -``` -> __Note:__ -> It is recommended to extract the Zephyr SDK bundle at one of the following locations: -> - $HOME -> - $HOME/.local -> - $HOME/.local/opt -> - $HOME/bin -> - /opt -> - /usr/local -> -> The Zephyr SDK bundle archive contains the `zephyr-sdk-` directory and, when extracted under `$HOME`, the resulting installation path will be `$HOME/zephyr-sdk-`. - -Run the Zephyr SDK bundle setup script: - -```sh -cd zephyr-sdk-0.16.8 -./setup.sh -``` -> __Note:__ -> You only need to run the setup script once after extracting the Zephyr SDK bundle. -> You must rerun the setup script if you relocate the Zephyr SDK bundle directory after the initial setup. - -Install udev rules, which allow you to flash most Zephyr boards as a regular user: - -```sh -sudo cp ~/zephyr-sdk-0.16.8/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d -sudo udevadm control --reload -./setup.sh -``` - -## Installing Espressif binary blobs - -To successfully build your ESP32 application on Zephyr, install Espressif binary blobs: - -```sh -cd ~/zephyrproject -west blobs fetch hal_espressif -``` - -## Building the application - -Remember I mentioned __west__ takes part in all stages of a Zephyr’s project life-cycle? Well, we’ll see it in action here again. Build the __hello_world__ project for the ESP32 board from the sample code folder. - -``` -cd ~/zephyrproject/zephyr/samples/hello_world -west build -b esp32_devkitc_wrover/esp32/procpu zephyr/samples/hello_world --pristine -``` - -## Flashing the binary - -Flashing the binary is quite simple: use a usb cable to connect you ESP board to you PC usb port and do the following: - -```sh -west flash -``` - -Afer executing the last command you must see the following messages: - -```sh -ninja: no work to do. --- west flash: using runner esp32 --- runners.esp32: reset after flashing requested --- runners.esp32: Flashing esp32 chip on None (921600bps) -esptool.py v4.7.0 -Found 33 serial ports -Serial port /dev/ttyUSB0 -Connecting.... -Detecting chip type... Unsupported detection protocol, switching and trying again... -Connecting.... -Detecting chip type... ESP32 -Chip is ESP32-D0WD-V3 (revision v3.1) -Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None -Crystal is 40MHz -MAC: b0:b2:1c:b4:6b:28 -Uploading stub... -Running stub... -Stub running... -Changing baud rate to 921600 -Changed. -Configuring flash size... -Auto-detected Flash size: 8MB -Flash will be erased from 0x00001000 to 0x00020fff... -Flash params set to 0x0230 -Wrote 131072 bytes at 0x00001000 in 1.8 seconds (590.9 kbit/s)... -Hash of data verified. - -Leaving... -Hard resetting via RTS pin... -``` - -Now execute the command: - -```sh -west espressif monitor -``` - - -If you have been following everything up to this point, after some ESP32’s boot messages, you should see the expected hello message: - -```sh -ets Jul 29 2019 12:21:46 - -rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) -configsip: 0, SPIWP:0xee -clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 -mode:DIO, clock div:2 -load:0x3ffb0000,len:6412 -ho 0 tail 12 room 4 -load:0x40080000,len:33216 -entry 0x40083a04 -I (31) boot: ESP Simple boot -I (31) boot: compile time Oct 17 2024 16:55:10 -W (31) boot: Unicore bootloader -I (31) spi_flash: detected chip: generic -I (34) spi_flash: flash io: dio -I (37) boot: chip revision: v3.1 -I (40) boot.esp32: SPI Speed : 40MHz -I (44) boot.esp32: SPI Mode : DIO -I (47) boot.esp32: SPI Flash Size : 8MB -I (51) boot: Enabling RNG early entropy source... -I (55) boot: DRAM: lma 0x00001020 vma 0x3ffb0000 len 0x190c (6412) -I (61) boot: IRAM: lma 0x00002934 vma 0x40080000 len 0x81c0 (33216) -I (67) boot: padd: lma 0x0000ab08 vma 0x00000000 len 0x54f0 (21744) -I (74) boot: IMAP: lma 0x00010000 vma 0x400d0000 len 0x2eb4 (11956) -I (80) boot: padd: lma 0x00012ebc vma 0x00000000 len 0xd13c (53564) -I (86) boot: DMAP: lma 0x00020000 vma 0x3f400000 len 0xc6c (3180) -I (92) boot: Image with 6 segments -I (95) boot: DROM segment: paddr=00020000h, vaddr=3f400000h, size=00C6Ch ( 3180) map -I (103) boot: IROM segment: paddr=00010000h, vaddr=400d0000h, size=02EB4h ( 11956) map - -I (143) heap_runtime: ESP heap runtime init at 0x3ffb40c0 size 175 kB. - -*** Booting Zephyr OS build v3.7.0-4642-g4152ab3cbba2 *** -Hello World! esp32_devkitc_wrover/esp32/procpu -``` -There you have it! Your development environment was properly configured and you have run your first application using Zephyr on ESP32! - -## Supported Features - -ESP32 support for Zephyr is growing. By the time I am writing this post, it includes the following peripherals and features: - -- UART -- I2C -- GPIO -- SPI -- SPI FLASH -- SPI RAM -- Timers -- Wi-FI -- Bluetooth -- GPIO -- TWAI -- E-Fuse -- ADC -- DAC -- MCPWM -- LEDPWM -- PCNT -- TRNG -- WATCHDOG -- ETH MAC -- SDHC -- FLASH ENCRIPTION -- OPENOCD -- MCUBOOT - -Please follow [here](https://github.com/zephyrproject-rtos/zephyr/issues/29394) for overall future road-map for ESP32 support. - -## Summary - -In this post, we saw how to set the environment for Zephyr RTOS and how to build a sample project for an ESP32 based board. - -Stay tuned to Zephyr’s documentation and repository for the most recent supported peripherals. Espressif Team keeps actively working on porting and supporting its SoCs on Zephyr. - - ->__Oct/2024 - Reviewd by Márcio Ribeiro__