1. 系統要求
- 操作系統：Ubuntu2404（64位）
- 磁盤空間：至少 8GB 可用空間（Zephyr 及其工具鏈較大）
2. 安裝必要工具
| Tool | Min. Version |
| CMake | 3.20.5 |
| Python | 3.10 |
| Devicetree compiler | 1.4.6 |
?2.1 安裝系統依賴
# 更新軟件源并安裝基礎工具
sudo apt update && sudo apt upgrade -y
sudo apt install -y --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 libmagic12.2 驗證主要依賴項版本
cmake --version
python3 --version
dtc --versioncmake version 3.22.1
CMake suite maintained and supported by Kitware (kitware.com/cmake).
Python 3.10.12
Version: DTC 1.6.12.3 獲取Zephyr和安裝Python依賴項
2.3.1 安裝Python venv安裝包
sudo apt install -y python3-venv2.3.2 創建Python 虛擬環境
# 創建虛擬環境
python3 -m venv ~/workspace/zephyr-venv2.3.3?激活虛擬環境
source ~/workspace/zephyr-venv/bin/activate2.3.4?安裝west
# 使用國內鏡像源速度快
pip install west -i https://pypi.mirrors.ustc.edu.cn/simple/2.3.5?獲取 Zephyr 源碼
# 初始化 Zephyr 項目
west init ~/workspace/zephyr-project
cd ~/workspace/zephyr-project
west update# west update主要下載submodules github源碼(zephyr-venv) Weston@PC:~/workspace/zephyr-project$ west update
=== updating acpica (modules/lib/acpica):
HEAD is now at 8d24867bc Merge pull request #5 from dcpleung/kernel/mm_z_phys_map_unmap_rename
=== updating cmsis (modules/hal/cmsis):
HEAD is now at d1b8b20 Backport CMSIS_6#102 to CMSIS 5.9.0
=== updating cmsis-dsp (modules/lib/cmsis-dsp):
HEAD is now at d80a49b2 do not generate warnings when scalar functions are used with MVE
=== updating cmsis-nn (modules/lib/cmsis-nn):
HEAD is now at e9328d6 manifest: zephyr module file
=== updating cmsis_6 (modules/lib/cmsis_6):
HEAD is now at 783317a3 TZ applications can be secure-only (#204)
=== updating edtt (tools/edtt):
HEAD is now at b9ca3c7 Fix for for python >= 3.11
=== updating fatfs (modules/fs/fatfs):
HEAD is now at 16245c7 fs: Update driver to version 0.15a
=== updating hal_adi (modules/hal/adi):
HEAD is now at 8f33130 fix(Other): Add 'static inline' keywords to Zephyr Timer Wrapper functions (#1379)
=== updating hal_altera (modules/hal/altera):
HEAD is now at 4fe4df9 uart: do not build hal uart driver
=== updating hal_ambiq (modules/hal/ambiq):
HEAD is now at 9da9656 add back missing files for apollo3 and apollo4
=== updating hal_atmel (modules/hal/atmel):
HEAD is now at ca7e4c6 sam3x: spi: missing adc macro
=== updating hal_bouffalolab (modules/hal/bouffalolab):
HEAD is now at c6c44b8 pinctrl: pinconfig: Add autogen
=== updating hal_espressif (modules/hal/espressif):
HEAD is now at e794f935ff zephyr: port: Heap adapter
=== updating hal_ethos_u (modules/hal/ethos_u):
HEAD is now at 50ddffc Cache optimizations
=== updating hal_gigadevice (modules/hal/gigadevice):
HEAD is now at 2994b7d README.md: add pllmf and pack exception for gd32a50x
=== updating hal_infineon (modules/hal/infineon):
HEAD is now at d7b8432 Update CYW20829 BLE FW blobs
=== updating hal_intel (modules/hal/intel):
HEAD is now at 0447cd2 Update pm_regs.h
=== updating hal_microchip (modules/hal/microchip):
HEAD is now at 15ca197 hal: microchip: mec5: Fix bugs in EC subsystem debug enable
=== updating hal_nordic (modules/hal/nordic):
HEAD is now at a5a2277 nrfx: drivers: rramc: Declare functions as unused
=== updating hal_nuvoton (modules/hal/nuvoton):
HEAD is now at be1042d hal:nuvoton:m55m1: support emac
=== updating hal_nxp (modules/hal/nxp):
HEAD is now at 5e5a498e mcux: wifi: nxp: support override TX power limit file
=== updating hal_openisa (modules/hal/openisa):
HEAD is now at eabd530 fix-double-promotion in fsl_xcvr_trim
=== updating hal_quicklogic (modules/hal/quicklogic):
HEAD is now at bad8944 HAL: eoss3_dev: add missing `__cplusplus` handling
=== updating hal_renesas (modules/hal/renesas):
HEAD is now at 9d68ee7 portable: rp_crc: add runtime reconfigure for CRC
=== updating hal_rpi_pico (modules/hal/rpi_pico):
HEAD is now at 7b57b24 Merge pull request #8 from ajf58/merge-2.1.0
=== updating hal_silabs (modules/hal/silabs):
HEAD is now at 40a0237 wiseconnect: Use static allocation for threads
=== updating hal_st (modules/hal/st):
HEAD is now at 9f81b44 sensor/stmemsc: Align stmemsc i/f to v2.9.1
=== updating hal_stm32 (modules/hal/stm32):
HEAD is now at 6e4716f8 dts: st: update pinctrls related to dcmipp pins
=== updating hal_tdk (modules/hal/tdk):
HEAD is now at 6727477 Merge pull request #8 from tdk-invn-oss/main
=== updating hal_telink (modules/hal/telink):
HEAD is now at 4226c7f drivers: Disable BLE support
=== updating hal_ti (modules/hal/ti):
HEAD is now at 258652a simplelink_lpf3: Add README.md
=== updating hal_wch (modules/hal/wch):
HEAD is now at 1de9d3e Add hal_wch based on the 'ch32v003fun' project
=== updating hal_wurthelektronik (modules/hal/wurthelektronik):
HEAD is now at e3e2797 Remove preprocessor warnings for not enabling float
=== updating hal_xtensa (modules/hal/xtensa):
HEAD is now at b38620c zephyr: Add SoC overlay for i.MXRT700 HiFi1 DSP
=== updating hostap (modules/lib/hostap):
HEAD is now at 8412f4b23 [noup] zephyr: remove zephyr wpas monitor socket pair
=== updating liblc3 (modules/lib/liblc3):
HEAD is now at 48bbd3e Rename lc3 python package to lc3py, and bump version to 1.1.2
=== updating libmctp (modules/lib/libmctp):
HEAD is now at b97860e build MCTP zephyr library only when CONFIG_MCTP is enabled
=== updating libmetal (modules/hal/libmetal):
HEAD is now at 14f5195 lib: update libmetal to SHA 9a21915a5f8f
=== updating littlefs (modules/fs/littlefs):
HEAD is now at ed0531d Merge pull request #15 from Jappie3/zephyr
=== updating loramac-node (modules/lib/loramac-node):
HEAD is now at fb00b383 zephyr: configure FragDecoder using Kconfig
=== updating lvgl (modules/lib/gui/lvgl):
HEAD is now at 1ed1ddd88 docs(Alif): add docs for Alif chip vendor (#7622)
=== updating mbedtls (modules/crypto/mbedtls):
HEAD is now at 5f8899343 Merge pull request #70 from tomi-font/bump_to_3.6.3
=== updating mcuboot (bootloader/mcuboot):
HEAD is now at 81315483 Revert "zephyr: arm: Update reading the flash image reset vector"
=== updating mipi-sys-t (modules/debug/mipi-sys-t):
HEAD is now at 33e5c23 Fix for warning of potential error using = instead of ==
=== updating net-tools (tools/net-tools):
HEAD is now at 986bfeb Replace native_posix with native_sim
=== updating nrf_hw_models (modules/bsim_hw_models/nrf_hw_models):
HEAD is now at d5b95fd grtc hal replacement: Fix bug in nrf_grtc_int_group_enable/disable()
=== updating nrf_wifi (modules/lib/nrf_wifi):
HEAD is now at d89b42a Remove recovery code for radio test
=== updating open-amp (modules/lib/open-amp):
HEAD is now at f7f4d08 lib: update open-amp lib to SHA 9a21915a5f8f
=== updating openthread (modules/lib/openthread):
HEAD is now at 3ae741f95 [instance] fix index computation in multi-instances context (#11099)
=== updating percepio (modules/debug/percepio):
HEAD is now at 49e6dc2 Merge branch 'main' into zephyr
=== updating picolibc (modules/lib/picolibc):
HEAD is now at 82d62ed1a zephyr: Disable LTO when building the library
=== updating segger (modules/debug/segger):
HEAD is now at cf56b1d readme: Add readme
=== updating tinycrypt (modules/crypto/tinycrypt):
HEAD is now at 1012a3e Fix warnings reported by UBSAN
=== updating trusted-firmware-a (modules/tee/tf-a/trusted-firmware-a):
HEAD is now at 713ffbf96 Merge pull request #4 from ceolin/v2.10.4
=== updating trusted-firmware-m (modules/tee/tf-m/trusted-firmware-m):
HEAD is now at e2288c13e Merge pull request #130 from tomi-font/bump_to_2.1.2
=== updating uoscore-uedhoc (modules/lib/uoscore-uedhoc):
HEAD is now at 54abc10 Merge pull request #5 from rlubos/upmerge-02-2025
=== updating zcbor (modules/lib/zcbor):
HEAD is now at 9b07780 Update version to 0.9.12.3.6 導入?Zephyr 環境變量
west zephyr-export2.3.7??安裝west python依賴包
# 使用國外鏡像源比較慢
west packages pip --install注意：永久切換pip使用國內鏡像源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cnpip config list# 恢復默認配置pip config unset global.index-url
pip config unset global.trusted-host常見鏡像源地址
| 鏡像名稱 | URL |
| 清華大學 |
|
| 阿里云 |
|
| 騰訊云 |
|
| 華為云 |
|
3. 安裝 Zephyr SDK
# 導出環境變量
echo "export ZEPHYR_BASE=~/workspace/zephyr-project/zephyr" >> ~/.bashrc
source ~/.bashrc# 下載并安裝 SDK
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.17.0/zephyr-sdk-0.17.0_linux-x86_64.tar.xz
# 解壓并安裝
tar xvf zephyr-sdk-0.17.0_linux-x86_64.tar.xz
cd zephyr-sdk-0.17.0
./setup.shZephyr SDK 0.17.0 Setup** NOTE **
You only need to run this script once after extracting the Zephyr SDK
distribution bundle archive.Install host tools [y/n]? y
Register Zephyr SDK CMake package [y/n]? yInstalling host tools ...Registering Zephyr SDK CMake package ...
Zephyr-sdk (/home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0/cmake)
has been added to the user package registry in:
~/.cmake/packages/Zephyr-sdkAll done.
Press any key to exit ...設置環境變量
echo "export ZEPHYR_TOOLCHAIN_VARIANT=zephyr" >> ~/.bashrc
echo "export ZEPHYR_SDK_INSTALL_DIR=$HOME/workspace/zephyr-sdk/zephyr-sdk-0.17.0" >> ~/.bashrc
source ~/.bashrc4. 驗證安裝
(1) 檢查環境
west --version
cmake --version
ninja --version
python --version# 所有命令應正常輸出版本號
West version: v1.3.0
cmake version 3.22.1
1.10.2.git.kitware.jobserver-1
Python 3.10.12(2) 編譯示例項目
cd ~/workspace/zephyr-project/zephyr
west build -b blackpill_f401cc samples/hello_world(zephyr-venv) polaris@PC:~/workspace/zephyr-project/zephyr$ west build -b blackpill_f401cc samples/hello_world
-- west build: generating a build system
Loading Zephyr default modules (Zephyr base).
-- Application: /home/polaris/workspace/zephyr-project/zephyr/samples/hello_world
-- CMake version: 3.22.1
-- Found Python3: /home/polaris/workspace/zephyr-venv/bin/python3 (found suitable version "3.10.12", minimum required is "3.10") found components: Interpreter
-- Cache files will be written to: /home/polaris/.cache/zephyr
-- Zephyr version: 4.1.99 (/home/polaris/workspace/zephyr-project/zephyr)
-- Found west (found suitable version "1.3.0", minimum required is "0.14.0")
-- Board: blackpill_f401cc, qualifiers: stm32f401xc
-- Found host-tools: zephyr 0.17.0 (/home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0)
-- Found toolchain: zephyr 0.17.0 (/home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0)
-- Found Dtc: /home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0/sysroots/x86_64-pokysdk-linux/usr/bin/dtc (found suitable version "1.6.0", minimum required is "1.4.6")
-- Found BOARD.dts: /home/polaris/workspace/zephyr-project/zephyr/boards/weact/blackpill_f401cc/blackpill_f401cc.dts
-- Generated zephyr.dts: /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/zephyr.dts
-- Generated pickled edt: /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/edt.pickle
-- Generated devicetree_generated.h: /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/include/generated/zephyr/devicetree_generated.h
-- Including generated dts.cmake file: /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/dts.cmake
Parsing /home/polaris/workspace/zephyr-project/zephyr/Kconfig
Loaded configuration '/home/polaris/workspace/zephyr-project/zephyr/boards/weact/blackpill_f401cc/blackpill_f401cc_defconfig'
Merged configuration '/home/polaris/workspace/zephyr-project/zephyr/samples/hello_world/prj.conf'
Configuration saved to '/home/polaris/workspace/zephyr-project/zephyr/build/zephyr/.config'
Kconfig header saved to '/home/polaris/workspace/zephyr-project/zephyr/build/zephyr/include/generated/zephyr/autoconf.h'
-- Found GnuLd: /home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0/arm-zephyr-eabi/arm-zephyr-eabi/bin/ld.bfd (found version "2.38")
-- The C compiler identification is GNU 12.2.0
-- The CXX compiler identification is GNU 12.2.0
-- The ASM compiler identification is GNU
-- Found assembler: /home/polaris/workspace/zephyr-sdk/zephyr-sdk-0.17.0/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
-- Using ccache: /usr/bin/ccache
-- Found gen_kobject_list: /home/polaris/workspace/zephyr-project/zephyr/scripts/build/gen_kobject_list.py
-- Configuring done
-- Generating done
-- Build files have been written to: /home/polaris/workspace/zephyr-project/zephyr/build
-- west build: building application
[1/140] Preparing syscall dependency handling[3/140] Generating include/generated/zephyr/version.h
-- Zephyr version: 4.1.99 (/home/polaris/workspace/zephyr-project/zephyr), build: v4.1.0-3774-gc35bb0de8023
[140/140] Linking C executable zephyr/zephyr.elf
Memory region Used Size Region Size %age UsedFLASH: 15996 B 256 KB 6.10%RAM: 4544 B 64 KB 6.93%IDT_LIST: 0 GB 32 KB 0.00%
Generating files from /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/zephyr.elf for board: blackpill_f401cc-b blackpill_f401cc：指定 Black Pill STM32F401CC 開發板- 首次編譯會下載工具鏈和依賴，耗時較長。
(3) 燒錄與調試
west flash --runner blackmagicprobe
west debug --runner blackmagicprobe
west attach --runner blackmagicprobe# 使用blackmagicprobe燒錄固件
west flash --runner blackmagicprobe
-- west flash: rebuilding
ninja: no work to do.
-- west flash: using runner blackmagicprobe
-- runners.blackmagicprobe: using GDB serial: /dev/ttyACM0
Remote debugging using /dev/ttyACM0
Target voltage: 2.45V
Available Targets:
No. Att Driver1 STM32F411 M4
Attaching to Remote target
warning: No executable has been specified and target does not support
determining executable automatically. Try using the "file" command.
0x08001ac8 in ?? ()
Loading section rom_start, size 0x194 lma 0x8000000
Loading section text, size 0x3448 lma 0x8000194
Loading section .ARM.exidx, size 0x8 lma 0x80035dc
Loading section initlevel, size 0x80 lma 0x80035e4
Loading section device_area, size 0x180 lma 0x8003664
Loading section sw_isr_table, size 0x2a8 lma 0x80037e4
Loading section gpio_driver_api_area, size 0x24 lma 0x8003a8c
Loading section reset_driver_api_area, size 0x10 lma 0x8003ab0
Loading section clock_control_driver_api_area, size 0x1c lma 0x8003ac0
Loading section uart_driver_api_area, size 0x4c lma 0x8003adc
Loading section rodata, size 0x2ec lma 0x8003b28
Loading section datas, size 0x4c lma 0x8003e14
Loading section device_states, size 0x18 lma 0x8003e60
Loading section .last_section, size 0x4 lma 0x8003e78
Start address 0x0800087c, load size 15996
Transfer rate: 29 KB/sec, 592 bytes/write.
[Inferior 1 (Remote target) killed]# 使用blackmagicprobe在線調試固件
west debug --runner blackmagicprobe
-- west debug: rebuilding
ninja: no work to do.
-- west debug: using runner blackmagicprobe
-- runners.blackmagicprobe: using GDB serial: /dev/ttyACM0
GNU gdb (Zephyr SDK 0.17.0) 12.1
Copyright (C) 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=arm-zephyr-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://github.com/zephyrproject-rtos/sdk-ng/issues>.
Find the GDB manual and other documentation resources online at:<http://www.gnu.org/software/gdb/documentation/>.For help, type "help".
Type "apropos word" to search for commands related to "word".
Remote debugging using /dev/ttyACM0
Target voltage: 2.48V
Available Targets:
No. Att Driver1 STM32F411 M4
Attaching to Remote target
warning: No executable has been specified and target does not support
determining executable automatically. Try using the "file" command.
0x08002b48 in ?? ()
Reading symbols from /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/zephyr.elf...
Loading section rom_start, size 0x194 lma 0x8000000
Loading section text, size 0x3448 lma 0x8000194
Loading section .ARM.exidx, size 0x8 lma 0x80035dc
Loading section initlevel, size 0x80 lma 0x80035e4
Loading section device_area, size 0x180 lma 0x8003664
Loading section sw_isr_table, size 0x2a8 lma 0x80037e4
Loading section gpio_driver_api_area, size 0x24 lma 0x8003a8c
Loading section reset_driver_api_area, size 0x10 lma 0x8003ab0
Loading section clock_control_driver_api_area, size 0x1c lma 0x8003ac0
Loading section uart_driver_api_area, size 0x4c lma 0x8003adc
Loading section rodata, size 0x2ec lma 0x8003b28
Loading section datas, size 0x4c lma 0x8003e14
Loading section device_states, size 0x18 lma 0x8003e60
Loading section .last_section, size 0x4 lma 0x8003e78
Start address 0x0800087c, load size 15996
Transfer rate: 30 KB/sec, 592 bytes/write.
(gdb) # 使用blackmagicprobe接入調試
west attach --runner blackmagicprobe
-- west attach: rebuilding
ninja: no work to do.
-- west attach: using runner blackmagicprobe
-- runners.blackmagicprobe: using GDB serial: /dev/ttyACM0
GNU gdb (Zephyr SDK 0.17.0) 12.1
Copyright (C) 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=arm-zephyr-eabi".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://github.com/zephyrproject-rtos/sdk-ng/issues>.
Find the GDB manual and other documentation resources online at:<http://www.gnu.org/software/gdb/documentation/>.For help, type "help".
Type "apropos word" to search for commands related to "word".
Remote debugging using /dev/ttyACM0
Target voltage: 2.39V
Available Targets:
No. Att Driver1 STM32F411 M4
Attaching to Remote target
warning: No executable has been specified and target does not support
determining executable automatically. Try using the "file" command.
0x08002b48 in ?? ()
Reading symbols from /home/polaris/workspace/zephyr-project/zephyr/build/zephyr/zephyr.elf...
(gdb) 如果看到 Hello World! zephyr 輸出，說明環境搭建成功！
問題： 解決github https下載失敗超時問題
git config --local url."git@github.com:".insteadOf "https://github.com/"這樣會將所有 https://github.com/ 開頭的 URL 自動替換為 SSH 協議
