Zephyr

Zephyr RTOS

Contract

Inputs

• Board target in board/soc form (west boards lists them).
• Zephyr version to pin (v4.4.2 is the current release on 2026-09-05; v3.7 is the older long-term branch) and the matching Zephyr SDK (1.0.1 on the same date).
• The peripherals the application needs, so the overlay and Kconfig can be scoped.
• A debug adapter, if hardware debugging is wanted (see openocd-jtag).

Procedure

1. Set up the workspace once. west init clones the manifest repository, west update fetches every module it lists, west zephyr-export registers the CMake package, west packages pip --install installs the Python requirements, and west sdk install fetches the toolchains. Done when: west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world succeeds from the workspace root.

   pip install west
   west init ~/zephyrproject
   west update
   west zephyr-export
   west packages pip --install
   west sdk install
   west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world
   west flash
   

   Board names: nrf52840dk/nrf52840, nucleo_f446re, rpi_pico/rp2040, esp32_devkitc_wroom/esp32/procpu, qemu_cortex_m3, native_sim. Read the serial console with any terminal program at the board's baud, for example screen /dev/ttyACM0 115200.

2. Lay out the application. find_package(Zephyr) pulls in the build system; app is the library target every Zephyr application adds sources to. Done when: the directory below builds for the chosen board.

   my_app/
   ├── CMakeLists.txt
   ├── prj.conf
   ├── app.overlay
   └── src/main.c
   

   cmake_minimum_required(VERSION 3.28.0)
   find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
   project(my_app)
   target_sources(app PRIVATE src/main.c)
   

3. Configure features in prj.conf. Each line is CONFIG_<symbol>=<value>; the build merges it over the board defaults. west build -t menuconfig and -t guiconfig browse the tree and show what each symbol depends on. Done when: build/zephyr/.config contains every symbol the application relies on.

   CONFIG_GPIO=y
   CONFIG_UART_CONSOLE=y
   CONFIG_LOG=y
   CONFIG_LOG_DEFAULT_LEVEL=3
   CONFIG_PRINTK=y
   CONFIG_HEAP_MEM_POOL_SIZE=4096
   CONFIG_MAIN_STACK_SIZE=2048
   

   LOG_DEFAULT_LEVEL values: 0 off, 1 error, 2 warning, 3 info, 4 debug.

4. Describe hardware in a devicetree overlay. The board's .dts is fixed; app.overlay adds nodes and changes properties. C code reaches nodes through the DT_* macros and the *_dt_spec helpers. Done when: GPIO_DT_SPEC_GET on the alias compiles and toggles the pin.

   / {
       leds {
           compatible = "gpio-leds";
           my_led: led_0 {
               gpios = <&gpio0 13 GPIO_ACTIVE_LOW>;
           };
       };
       aliases { led0 = &my_led; };
   };
   
   &uart0 { current-speed = <115200>; };
   &spi1 { status = "disabled"; };
   

   #include <zephyr/devicetree.h>
   #include <zephyr/drivers/gpio.h>
   
   static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios);
   
   gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
   gpio_pin_toggle_dt(&led);
   

5. Log through the logging subsystem. LOG_MODULE_REGISTER names the module and sets its compile-time level; the backend is a Kconfig choice. Done when: the log lines appear on the chosen backend with the module name prefix.

   #include <zephyr/logging/log.h>
   LOG_MODULE_REGISTER(my_module, LOG_LEVEL_DBG);
   
   LOG_INF("sensor %d", value);
   LOG_WRN("battery %d%%", battery_pct);
   LOG_ERR("spi %d", ret);
   LOG_HEXDUMP_DBG(buf, len, "raw");
   

   CONFIG_LOG=y
   CONFIG_LOG_BACKEND_UART=y
   CONFIG_LOG_BACKEND_RTT=y
   CONFIG_LOG_PROCESS_THREAD_STACK_SIZE=1024
   

6. Run on the host with native_sim. Zephyr links into a Linux executable; the UART appears on a pseudo-terminal whose path the program prints at start. Done when: ./build/zephyr/zephyr.exe prints the application's log lines and exits under gdb with a readable backtrace.

   west build -b native_sim my_app
   ./build/zephyr/zephyr.exe
   ./build/zephyr/zephyr.exe --help     # native_sim command-line options
   gdb --args ./build/zephyr/zephyr.exe
   

   Use native_sim for unit tests and CI; validate timing, DMA, and peripheral behavior on hardware.

7. Debug on hardware. west debug starts the board's runner (OpenOCD, J-Link, or pyOCD) and GDB together; west attach connects without flashing. For thread-aware info threads through OpenOCD, set CONFIG_DEBUG_THREAD_INFO=y so the kernel emits the symbols OpenOCD's RTOS support reads. Done when: west debug stops at main and info threads lists the kernel threads.

   west debug
   west attach
   

   references/west-manifest.md covers pinning Zephyr and adding a module in west.yml.

Failure and recovery

Output

An application directory that builds for the named board and for native_sim, with prj.conf, overlay, and sources as designed, plus the west command lines that build, flash, and debug it.