ZephyrでM5Stack ATOM Liteを動かしてみた：環境構築とハマりポイントまとめ

Zephyrは、Linux Foundationが主導して開発している軽量でセキュリティに強いリアルタイムOS (RTOS) です。特に以下のような特徴を持ち、近年組込みIoT製品での採用が増えています。

🔐 セキュリティ重視の設計
セキュアブート、署名付きファームウェア、メモリ保護など

🧩 モジュール構成
必要な機能だけを選んでビルドできる

📡 IoT向け通信プロトコルの豊富なサポート
Bluetooth LE、Wi-Fi、IPv6、MQTT など

🌍 クロスプラットフォーム対応
200以上のボードをサポート。ESP32、nRF、STM32なども含む

🧾 商用にも使いやすいライセンス (Apache 2.0)

今回の記事では、このZephyrを M5Stack ATOM Lite（ESP32） 上で動かすための環境構築手順と、ハマりポイントをまとめます。

TL;DR（まとめ）

M5Stack ATOM LiteでZephyrは動く（ただしちょっと工夫が必要）
WSL2からUSB接続にはusbipd-winが必要
screenは強制終了に注意、再接続時はプロセス確認を
CIでビルド確認済み（GitHub Actionsでesp32向けbuild可能）
- https://github.com/tamegai-m/zephyr

はじめに

本記事の目的
- 「Zephyrって、なんかかっこいいRTOSっぽいぞ！」
  そんな軽い気持ちで始めたのがきっかけでした。
  せっかく M5Stack ATOM Lite 上で動作確認できたので、
  同じようにチャレンジしたい人の参考になればと思って記事にしました！
対象読者
- Zephyrを触ってみたいけど、最初の一歩でつまずいている人
- M5Stack ATOM Lite (ESP32-PICO-D4) を活用したい人
- WSL2＋GitHub Actionsなどの CI ビルド環境にも興味がある人
ゴール
- Zephyr の Hello World を M5Stack ATOM Lite で動かす
- CI（GitHub Actions）で自動ビルドできるようにする
- よくあるエラーや罠を回避できるようになる

開発環境

使用したPC
- Windows11 + WSL2(Ubuntu-22.04)
Zephyr / hal_espressif バージョン
- Zephyr: 196eeeb381db9a8415b72a44414aee33453efed2
- hal_espressif: 1892bfe6ffc859885bc2b0f2e06b6ad9ee436e6b
M5Stack ATOM Lite（ESP32-PICO-D4）
ESP32 ツールチェイン: xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch5
GitHub Actions のランナー: ubuntu-22.04

1. 環境構築手順（WSL2編）

必要なパッケージのインストール

sudo apt update && sudo apt install -y \
  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 g++ unzip

ESP32用ツールチェインのインストール
以下のコマンドで、ESP32用のツールチェインをセットアップします：

mkdir -p ~/esp
cd ~/esp
wget https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch5-linux-amd64.tar.gz
tar -xzf xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch5-linux-amd64.tar.gz

echo 'export ZEPHYR_TOOLCHAIN_VARIANT=espressif' >> ~/.bashrc
echo 'export ESPRESSIF_TOOLCHAIN_PATH=$HOME/esp/xtensa-esp32-elf' >> ~/.bashrc
source ~/.bashrc  # 環境変数が反映されます。忘れるとビルドできません！

westのインストールとセットアップ

pip3 install --user west
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc  # 環境変数が反映されます。忘れるとビルドできません！

Zephyrプロジェクトの初期化

mkdir -p ~/zephyrproject
cd ~/zephyrproject
west init
west update
west zephyr-export
pip3 install --user -r zephyr/scripts/requirements.txt

2. ビルドと実行

M5Stack ATOM Lite（ESP32-PICO-D4 rev 1.1）は Zephyr の正式サポート対象外のリビジョンでした。このままだと、実行時に警告が出ます。その警告を抑制して正式に動作させるために、samples/hello_world/prj.confに追記が必要です。

CONFIG_ESP32_USE_UNSUPPORTED_REVISION=y

west build コマンドによるビルド

cd zephyr
west build -b m5stack_atom_lite/esp32/procpu samples/hello_world

USBポートの WSL 接続設定（usbipd）
- WSL2 上では west flash はそのままでは USBデバイスにアクセスできません。今回はusbipd を使ってWSL2にUSBを通す方法をとりました。
  https://github.com/dorssel/usbipd-win/releases/tag/v5.0.0
  からusbipd-win_5.0.0_x64.msiをダウンロードしてインストールします。
- USBデバイスのバスIDを確認（Windowsのコンソール）

usbipd list

WSLにアタッチ（Windowsのコンソール)

usbipd attach --busid 1-4 --wsl=Ubuntu-22.04

Permissionを付与する（ユーザーを dialout グループに追加）(WSL2)

sudo usermod -aG dialout $USER

その後、WSL を一度完全に閉じて再起動してください（再ログインが必要です）。
west flash によるデバイスへの書き込み
- 再起動したらM5Stack ATOM LiteをUSBで接続して書き込みます。

west flash

書き込みが成功したら、出力を見て動作確認

screen /dev/ttyUSB0 115200

M5Stack ATOM Liteのリセットボタンを押すと・・・

mode:DIO, clock div:2
load:0x3ffb0000,len:6032
load:0x40080000,len:34144
entry 0x4008379c
I (30) soc_init: ESP Simple boot
I (30) soc_init: compile time Mar 26 2025 15:36:25
W (30) soc_init: Unicore bootloader
I (31) soc_init: chip revision: v1.1
E (34) soc_init: You are using ESP32 chip revision (1) that is unsupported. While it may work, it could cause unexpected behavior or issues.
E (46) soc_init: Proceeding with this ESP32 chip revision is not recommended unless you fully understand the potential risk and limitations.
I (59) flash_init: SPI Speed      : 40MHz
I (62) flash_init: SPI Mode       : DIO
I (66) flash_init: SPI Flash Size : 4MB
I (70) boot: DRAM: lma 0x00001020 vma 0x3ffb0000 len 0x1790   (6032)
I (76) boot: IRAM: lma 0x000027b8 vma 0x40080000 len 0x8560   (34144)
I (82) boot: IRAM: lma 0x0000ad28 vma 0x00000000 len 0x52d0   (21200)
I (88) boot: IMAP: lma 0x00010000 vma 0x400d0000 len 0x3154   (12628)
I (94) boot: IRAM: lma 0x0001315c vma 0x00000000 len 0xce9c   (52892)
I (100) boot: DMAP: lma 0x00020000 vma 0x3f400000 len 0xc7c    (3196)
I (106) boot: Image with 6 segments
I (110) boot: IROM segment: paddr=00010000h, vaddr=400d0000h, size=03154h ( 12628) map
I (117) boot: DROM segment: paddr=00020000h, vaddr=3f400000h, size=00C7Ch (  3196) map
I (136) boot: libc heap size 175 kB.
I (136) spi_flash: detected chip: gd
I (136) spi_flash: flash io: dio
*** Booting Zephyr OS build 196eeeb381db ***
Hello World! m5stack_atom_lite/esp32/procpu

3. ハマりポイントと対策

USB認識されない（usbipdの罠）
- WSL2からUSBは、標準ではみえません。usbipdユーティリティで、WSL2からアクセスできるようにします。
パーミッションエラー
- usbipdだけだと、アクセス件がなく警告が出ます。usermodでアクセス権を付与する必要があります。
/dev/ttyUSB0 が busy
- screen /dev/ttyUSB0 115200は強制終了すると画面は閉じてもプロセスが残ってしまいます。そのため再度screen /dev/ttyUSB0 115200してもエラーになります。pkill screen等でプロセスを終了するとうまくいきます。

4. GitHub Actions で CIビルド

GitHub に fork して Actions 設定
- 実は今回の試みは、下記の思考回路でgithub actionスクリプトを最初に書きました。
1. CI作成を目指して手元でビルドする。（これだけだとTry & Errorで再現性が大変）
2. どうせなら再現性のあるやり方で。それなら最初からCIありきで作成してしまおう。
3. じゃーまずForkして・・・yml書いて、push・・・yml修正・・push・・の繰り返し。
4. CI完成。じゃー手元でビルド、実機で動いたーー。
- 思い返してみれば、非常に効率的なアプローチだったのではと思います。
成功した設定ファイルの内容
- プロジェクト直下の .github/workflows/build-esp32.yml に以下を記述しました。

name: Build for M5Stack ATOM Lite

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  build-esp32:
    runs-on: ubuntu-22.04

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y python3-pip cmake ninja-build gperf ccache dfu-util \
            device-tree-compiler wget xz-utils file make gcc git unzip

      - name: Install west and Python deps
        run: |
          pip3 install --upgrade pip
          pip3 install west
          pip3 install -r scripts/requirements.txt

      - name: Initialize Zephyr workspace
        run: |
          west init -l .
          west update
          west zephyr-export

      - name: Setup ESP32 toolchain
        run: |
          mkdir -p ~/esp
          cd ~/esp
          wget https://dl.espressif.com/dl/xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch5-linux-amd64.tar.gz
          tar -xzf xtensa-esp32-elf-gcc8_4_0-esp-2021r2-patch5-linux-amd64.tar.gz
          echo "ZEPHYR_TOOLCHAIN_VARIANT=espressif" >> $GITHUB_ENV
          echo "ESPRESSIF_TOOLCHAIN_PATH=$HOME/esp/xtensa-esp32-elf" >> $GITHUB_ENV
      
      - name: Build hello_world for M5Stack ATOM Lite
        working-directory: ${{ github.workspace }}
        run: |
          export ZEPHYR_TOOLCHAIN_VARIANT=espressif
          export ESPRESSIF_TOOLCHAIN_PATH=$HOME/esp/xtensa-esp32-elf
          west build -b m5stack_atom_lite/esp32/procpu samples/hello_world \
            -- -DBOARD_ROOT=${{ github.workspace }}

zip ダウンロードもできるように！
- CIで作成したバイナリをzipファイルとしてダウンロードできると嬉しいと思って、build-esp32.ymlの最後にこれを追記しました。これでCIの成果物を実機で動かすことがすぐにできて嬉しいはず・・

     - name: Upload firmware artifact
        uses: actions/upload-artifact@v4
        with:
          name: atom-lite-firmware
          path: build/zephyr/zephyr.*

5. 今後の展望

Wifiを動かしたい
- この実機での動作確認を終えて、記事を書き始めたとき、ふと「同じことをやってる人はいないのかなー？」ってgoogle検索したら、ありました。
- https://qiita.com/hisashij/items/6551c48be94fd1f8a2e5
- なんと2020年にやってる、すごい。ただこのときのZephyrはWifiが動かないらしく、ちょっと寂しい。なんとか自分が動かしてみたい。
PR投稿 or 本家 Issue にするか検討中
- 作ったCIは、Zeohyrプロジェクトの人々の役に立つかも。PRだす？Issue書く？？なんか貢献したいですね。
FirebaseのRealtime Databaseのpush通知はできるのか？？
- 昨年、Realtime Dabaseからのレコード新規作成・更新のデバイス(FreeRTOS)へのpush通知を作って、大変感激しました。 Zephyrでも同じことできないかなー。MQTT使うとかしないといけないか・・tryしてみたい。

おわりに

苦労した点と学び
- jenkinsはいじったことあるけど、github actionは初めて書きました。それなりに戸惑いはありましたが、「最終的にGitHub Actionsで生成されたbin/zipを使ってM5Stack ATOM Liteが起動し、Hello Worldが出た」という感動は忘れられない！！し大変勉強になりました。またZephyrがセキュリティ重視の設計で、これからどんどん利用されることを考えると、貴重な経験になったこと間違いなし。
コメント歓迎！
- 「もっと簡単なやり方あるよー」とか、「ここで躓きましたー」なんてコメントお待ちしてます。
- Zephyrに興味ある方、初心者でもM5Stack ATOM Liteで動かせるので、ぜひトライしてみてください！「できたー」とかのコメントもお待ちしてます。

関連リンク

2020年にZephyrを早々と動かした貴重な記事です。（hisashijさん）
- https://qiita.com/hisashij/items/6551c48be94fd1f8a2e5
今回のCIを動かしたリポジトリ
- https://github.com/tamegai-m/zephyr
CIで作成したバイナリ
- https://github.com/tamegai-m/zephyr/actions/runs/14084009367/artifacts/2823553098