Zephyr RTOS on ESP32 — First Steps

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.
• Espressif officially supports Zephyr RTOS on its devices. Visit the Product page.
• Check if your device is supported. Users can track the development status of Zephyr on Espressif devices by following the Support Status Page.

Installation

#

• Follow the Official Getting Started Guide
• 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. Vendor refers to the board manufacturer. Many different vendors, including Espressif itself, use Espressif chips.
  • Boards Folder in Github.
• 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 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.

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.
• 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. Further explanation:
  • Zephyr project configuration is based on Kconfigs. More about it here.
  • You can search 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.
  • 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 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 <board> 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

#

• 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
• The Pull-Up Resistor Channel also has good tutorials. ESP32 on Zephyr OS

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 was published on Medium, at the ESP Journal. It was rewritten for the current format.