1. はじめに
これまで Zephyr を紹介する際、何度か下記リポジトリをベースに解説してきました。
このリポジトリは、実運用を想定した環境構築手順とデバッグ環境を提供しており、
本記事では、これを使った VSCode と連携したデバッグや書き込みなどの使い方について解説していきます。
2. 環境構築
2.1. 環境構築の進め方
環境構築に関しては、先述リポジトリの README.md から OS 毎の詳細ページに飛んで進めてください。
Linux 環境だと初回時に udev rule を設定する必要があるかもしれません。OpenOCD がうまく動作しない場合はこちらを試してください。
https://docs.zephyrproject.org/latest/develop/beyond-GSG.html#setting-udev-rules
Windows 環境だと、ユーザー名に空白文字が含まれている(e.g. C:\Users\Yamada Taro)と環境構築に失敗することを確認しています。
無難な回避策として C:\ や D:\ 直下に配置するなどがあります。
なお、筆者は Mac 環境を持っておらず動作未確認なため、公式ページに沿って進めてください。
既に公式ドキュメントに沿って環境構築済みな方は、次のページに沿って進めてください。
2.2. 新規に環境を構築 (nRF54L15-DK用)
cd C:\zephyrproject
git clone https://github.com/Corgeek/ZephyrOpsPlaybook.git playbook -b nordic
python -m venv .venv
.venv\Scripts\activate
west init -l playbook
west update
cmd /c zephyr\scripts\utils\west-packages-pip-install.cmd
mkdir ~/zephyrproject
cd ~/zephyrproject
git clone https://github.com/Corgeek/ZephyrOpsPlaybook.git playbook -b nordic
python3 -m venv .venv
source .venv/bin/activate
pip install west
west init -l playbook
west update
west packages pip --install
2.3. 既存環境の構成
公式の手順通りに環境を構築していれば、以下の構成になっているはず。
└── zephyrproject/
├── .venv/ # python の仮想環境(.venv で固定必須)
├── .west/ # west.yaml や zephyr ディレクトリの配置情報など
├── bootloader/ # MCUboot 関連の外部ライブラリ
├── modules/ # SoC固有のHALやファイルシステム、センサー類などの外部ライブラリ群
├── tools/ # PC 側のツール群
└── zephyr/ # zephyr 公式リポジトリ
2.4. 既存環境への追加手順
Windows では、C:\ 直下に zephyrproject を配置している前提で進めます。
cd C:\zephyrproject
git clone https://github.com/Corgeek/ZephyrOpsPlaybook.git playbook
rmdir /S /Q .west
.venv\Scripts\activate
west init -l playbook
west update
cmd /c zephyr\scripts\utils\west-packages-pip-install.cmd
Linux では${HOME}直下に配置している前提で進めます。
cd ~/zephyrproject
git clone https://github.com/Corgeek/ZephyrOpsPlaybook.git playbook
rm -rf .west
west init -l playbook
west update
west packages pip --install
2.5. 構築後のディレクトリ構成
環境を構築した直後は以下のようなディレクトリ構成になります。
本記事では playbook という名前で git clone している想定で話を進めます。
└── zephyrproject/
├── .venv/ # python の仮想環境(.venv で固定必須)
├── .west/ # west.yaml や zephyr ディレクトリの配置情報など
├── bootloader/ # MCUboot 関連の外部ライブラリ
├── modules/ # SoC固有のHALやファイルシステム、センサー類などの外部ライブラリ群
├── playbook/ # git clone で落としてきた ZephyrOpsPlaybook リポジトリ
└── zephyr/ # zephyr 公式リポジトリ
3. 初回時の設定
3.1. 開発対象のターゲットボードを設定
playbook の機能を活かすためには、初回に setup スクリプトを実行する必要があります。
これを行う事で、VSCode 上でデバッガが利用でき、VSCode のコード補完やジャンプ機能といった IntelliSense もフル活用できるメリットを得られます。
もちろん、従来の CUI 開発も阻害せず活用できます。必要に応じて使い分けるとより快適になります。
3.2. 初回時の設定
ビルド対象のボードを playbook/scripts/setup.bat (Windows)、もしくは playbook/scripts/setup.sh (linux) を編集して指定します。
ここでリストアップされていないボードを設定する方法については、次のページで。
3.2. ボード名称の確認方法
公式サイトにボード毎の専用ページが用意されており、ボード名はそこに記載されています。
例えば Nucleo F401RE だと下記個別ページに記載されています。
# From the root of the zephyr repository
west build -b nucleo_f401re samples/hello_world
west debug
ここで指定している -b nucleo_f401re が対象で、この nucleo_f401re を setup.sh / setup.bat に BOARD_TYPE として設定します。
その他、使用したいターゲットボードを探す場合は以下を利用してください。
3.3. 初回セットアップの実行
ボードの指定が終わったらそのスクリプトを実行すると、どの BOARD_TYPE とどの SDK を使う設定になったかが表示されます。
ただし、Zephyr のバージョン毎に SDK の最低バージョンが指定されていますが、この script ではその範囲まで検査していません。例えば Zephyr v4.4.0 以降から SDK v1.0.0 以上が必要ですが、それを検知できません。
3.4. セットアップ後のファイルの配置
setup 実行により、.vscode 用の設定ファイルと scripts/*.bat が配置されます。
└── zephyrproject/
├── .venv/
├── .vscode/ # vscode 用の設定ファイル群
├── .west/
├── bootloader/
├── modules/
├── playbook/
│ ├── .vscode/ # vscode 用の設定ファイル群(内容は上段の .vscode と同じ)
: :
│ └── scripts/ # ファームウェアに直接関与しない script 置き場
│ ├── build.bat # build, rebuild, flash 機能を提供するスクリプト
│ ├── debug.bat # west debugserver 機能を提供するスクリプト
│ ├── stop.bat # debug 終了時に強制的に debugserver を止めるスクリプト
│ ├── setup.bat # 実行した setup.bat / setup.sh など
│ └── west_env.bat # setup.bat / setup.sh で生成された環境変数ファイル
└── zephyr/
なお、Linux 側でも *.sh とせず *.bat としていますが、VSCode 側の動作を統一するのが目的です(引数も /r /f といった dos style にしているのも同じ理由)。
3.5. build.bat の動作確認
cd /d C:\zephyrproject\playbook
scripts/build.bat
cd ~/zephyrproject/playbook
./scripts/build.bat
※ スクリプトを実行する際のワークディレクトリは必ずしも playbook である必要はありません。
3.6. scripts/*.bat の解説
scripts/*.bat を利用することで事前に source .venv/bin/activate を行う手間を省けます。その他、debug.bat と stop.bat を用意していますが、それぞれのコマンドや引数は以下の挙動を取ります。
| 引数 | 挙動 | 最終的なコマンド |
|---|---|---|
build.bat /f |
対象のボードへ書き込み(flash) | west flash |
build.bat /r |
build ディレクトリの削除を行った後ビルド(実質 rebuild) | west build -p -b ${BOARD_TYPE} . |
debug.bat |
該当ボードを 3333 ポートでリモートデバッグ状態で待機 | west debugserver |
stop.bat |
west コマンドの停止。VSCode 側がリモートデバッグから抜ける時、綺麗に停止してくれないので明示的に停止 |
taskkill /IM west.exe /F or pkill -f "west debugserver"
|
4. VS Code の起動
4.1. ディレクトリを開く
VSCode で zephyrproject ディレクトリを開くことで、VSCode からでも先述の build.bat, flash.bat, debug .bat が利用できるようになっています。
4.2. プロジェクトのビルド
ビルドを行う場合、Ctrl + Shift + B でコマンドパレットを呼び出し、そのまま b を入力すれば build が、r を入力すれば rebuild が選択されるためその状態で Etner キーを押せば実行できます。
4.3. ファームウェアの書き込み
ビルドと同様に Ctrl + Shift + B でコマンドパレットにフォーカスを移し、f を入力すると flash が選択されるため、その状態で Enter を押すだけです。
4.4. 実機上でのデバッグ
デバッグは2ステップ踏む必要があります。
-
Ctrl + Shift + B->d-> Enter を押すと実機側がデバッグ待機状態に移行 -
F5を押すと VSCode と実機が連携を開始
4.5. その他連携について
playbook ではなく zephyrproject ディレクトリを開くいている事で、modules や zephyr ディレクトリも参照でき、コード補完や RTOS 本体側へのジャンプやステップ実行、レジスタ書き換えなど VSCode の機能をフル活用できるようになります。
5. その他注意点
5.1. ディレクトリ名の変更や移動
ディレクトリ名の変更や移動を行うと環境が壊れてしまうため再設定が必要です。
※ playbook に限った話ではなく python と zephyr 本体側の仕様
例えば ~/zephyrproject 以下に環境を構築していましたが、これを ~/RTOS に移動させる場合、以下の手順で .venv と .west ディレクトリを削除した後 west init -l で再構築が必要です。
rmdir /S /Q .venv .west
python -m venv .venv
.venv\Scripts\activate
pip install west
west init -l playbook
cmd /c zephyr\scripts\utils\west-packages-pip-install.cmd
rm -rf .venv .west
python3 -m venv .venv
source .venv/bin/activate
pip install west
west init -l playbook
west packages pip --install
5.2. Zephyr のバージョンを変更する場合
zephyrproject/zephyr に Zephyr RTOS 本体のソースコードが配置されており、
2026/5/15 現在は playbook/west.yaml 側で v4.4.0 に固定しています。
これを例えば一時的に最新版に置き換えたい場合、以下の手順が必要です。
projects:
- name: zephyr_public
repo-path: zephyr.git
path: zephyr
remote: upstream
revision: main <- v4.4.0 を書き換える
clone-depth: 1
そして、west.yaml を変更した場合、都度 west update と pip もそれに合わせたバージョンへと更新する必要があります。
※ playbook ではブランチ毎に west.yaml が異なります。切り替える際に都度下記コマンドの実行をお願いします。
taka@pembroke:~/zephyrproject$ source .venv/bin/activate
(.venv) taka@pembroke:~/zephyrproject$ west update
(.venv) taka@pembroke:~/zephyrproject$ west packages pip --install
west.yaml を使った管理に関しては以下の記事でもまとめています。
6. VSCode 連携の概要
6.1. playbook/scripts の概要
基本的な VSCode 連携は .vscode と scripts 以下で行っています。
.vscode/tasks.json で build, rebuild, flash, debug のコマンドを定義し、それらから各種 *.bat を呼んでいるだけです。
zephyrproject や SDK などのディレクトリは自由に選べるようにするため、setup スクリプト実行時にそれら絶対パスを .vscode/settings.json に吐き出す、という仕組みにしています。
6.2. ターゲットボードの追加の仕方(scripts側)
編集対象と記載内容は以下の通り。
└── zephyrproject/
└── playbook/ # ZephyrOpsPlaybook リポジトリ
└── scripts/ # scripts をまとめたディレクトリ
├── support/ # target board 毎のオプションなど
│ └── runner.json # jlink, openocd, pyocd, stm32cubeprogrammer などのツールを指定
├── setup.sh # BOARD_TYPE を指定し、setup.py を呼ぶ bash 用シェルスクリプト
└── setup.bat # BOARD_TYPE を指定し、setup.py を呼ぶ Windows 向けバッチファイル
VSCode との連携だけが目的であれば、setup で BOARD_TYPE を指定するだけで可能です。
ただし、runner.json による runnner 指定は明示的にしていたほうが良さそうです。
(経験上 openocd を明示的に指定したほうが無難)
6.3. ターゲットボードの追加の仕方(ソースコード側)
playbook をベースに進めたい場合、ボード依存部に変更を加えます(必須ではありません)。
└── playbook/
├── CMakeLists.txt # BOARD_TYPE 毎に参照する prj.conf を分岐(もっと賢い方法あるかも)
├── include/
│ ├── boards/ # ボード毎の固有処理用の定義
│ └── unique.h # ボード毎の分岐を追加
└── boards/ # ファームウェアに直接関与しない script 置き場
├── bbc, st, nxp, etc. # ベンダー毎のディレクトリ等、Zephyr 本体側に準拠
├── *.overlay # ボード毎の dts の個別設定
└── CMakeLists.txt # ボード毎の分岐を追加
7. 【おまけ】ターゲットボード個別設定等
7.1. rpi_pico / rpi_pico2
Linux 版 Zephyr SDK には openocd が同梱されていますが、rpi_pico / rpi_pico2 向けの対応が入っていません。
rpi_pico / rpi_pico2 用の openocd をビルドして導入する手順は以下の記事に記載してあるため、必要に応じて導入してください。
7.2. Teensy4.0 / Teensy4.1
Teensy は以下の公式ページから専用の Programmer をインストールする必要があります。
Linux の場合は Teensy を正しく検出できるように udev rule を設定しておく必要があり、その設定ファイルも下記ページの Linux ページに置かれています。
8. まとめ
今回、Zephyr の 第5回 Meetup ＠高知でハンズオン形式で触ってもらう資料として準備しました。
playbook/scripts 部分はちょっと古めな ChatGPT でラフに作ったものですので、色々作り変えて改善していただければと思います。
9. 【おまけ2】 Meetup で配布された Nordic nRF54L15-DK 用の設定を簡易追加
playbook に nordic ブランチを用意して nRF54L15-DK 用の分岐を作成しておきました。
git checkout origin/nordic -b nordic
./scripts/setup.sh
./scripts/build.bat /r
./scripts/build.bat /f
その後、core/main.c を以下のようにすると 4つのLEDが明滅するようになり、scripts/debug.bat も利用できるようにしています。
int main(void)
{
uni_board_init();
gpio_pin_configure(USER_LED0.port, USER_LED0.pin, GPIO_OUTPUT_ACTIVE);
gpio_pin_configure(USER_LED1.port, USER_LED1.pin, GPIO_OUTPUT_ACTIVE);
gpio_pin_configure(USER_LED2.port, USER_LED2.pin, GPIO_OUTPUT_ACTIVE);
gpio_pin_configure(USER_LED3.port, USER_LED3.pin, GPIO_OUTPUT_ACTIVE);
while (true) {
gpio_pin_toggle(USER_LED0.port, USER_LED0.pin);
gpio_pin_toggle(USER_LED1.port, USER_LED1.pin);
gpio_pin_toggle(USER_LED2.port, USER_LED2.pin);
gpio_pin_toggle(USER_LED3.port, USER_LED3.pin);
k_msleep(1000);
}
return 0;
}