M5Stack版StackChan：公式FWをWindows 11で動かすまでの手順— v1.4.1 / 2026年5月17日時点のビルド記録

2026年5月17日 07:58

M5Stack版 StackChan - ｽﾀｯｸﾁｬﾝを変更する

みなさん、ｽﾀｯｸﾁｬﾝしてますか？！
ｽﾀｯｸﾁｬﾝの良い所は「ソースが公開されていて、自分の好きなように自由に変更できることころ」です。昨日のｽﾀｯｸﾁｬﾝもくもく会から触り始めましたが、ソースをDLしてビルドしようとしたらはまりましたので、試行錯誤した内容をシェアします。この記事は、以下のブログを参考にさせていただきました。改めてありがとうございます。

何はともあれ、元に戻す方法を確認

色々触る前に、戻す方法を確認しておきましょう。
ビルドがまちがって失敗しても「M5Burner」というソフトウェアで、出荷時のユーザーデモの状態に戻ることができます。まずこれで失敗しても復元できることを確認でし、安心していじることができます。

例えばWindows版をダウンロードすると「M5Burner-v3-beta-win-64.zip」という圧縮ファイルが取得できるので、これを適当な場所で解凍。中にある「M5Burner.exe」を起動します。

M5Burnerでは様々なアプリがDLできますが「StackChan-UserDemo」が出荷時にインストールされているアプリです。また”黄色枠のバージョンが、基本的にGithubページのReleseバージョンと対応”しています。

本題：この記事で解決すること

検証commit: m5stack/StackChan @ da156e1（2026年5月時点のmain）
発生したエラー: expression_emote.h not found
解決策: core.autocrlf=false + C:\m5sc 再clone
補足：自前ビルド版では、StackChan Worldアプリ連携やAvatarモードについて、M5Burner公式版と挙動が異なる箇所があります。本文末尾に追記しました。

Windows 11環境で、M5Stack版 StackChan 公式FWをビルドしようとしたところ、python fetch_repos.py 実行時に xiaozhi-esp32.patch が当たらず、その後の idf.py build で次のエラーが出ました。

fatal error: expression_emote.h: No such file or directory

原因は、Git for Windows の core.autocrlf=true により、パッチ適用対象ファイルの改行が変わっていたことでした。

この記事では、core.autocrlf=false にしたうえで C:\m5sc を丸ごと再cloneし、M5Stack版 StackChan公式FWをビルド、実機書き込み、起動確認するところまでをまとめます。

今回の検証では、ESP-IDF v5.5.4 でビルドに成功しました。

なお、この手順は m5stack/StackChan のリポジトリ状態に依存します。本記事は 2026年5月17日時点のmain（commit da156e1）での検証記録です。

最新の main では fetch_repos.py や xiaozhi-esp32.patch の内容が更新されている可能性があるため、もし手順通りに動かない場合は、上記commitに戻して試すか、最新の Issues を確認してください。
* fetch_repos.py fails if git autocrlf is true / Issue #62:
https://github.com/m5stack/StackChan/issues/62

同じcommitに戻す場合：
この `git checkout da156e1` は、`python fetch_repos.py` を実行する前に行ってください。

cd C:\m5sc
git checkout da156e1
cd C:\m5sc\firmware
python fetch_repos.py

目的

M5Stack版 StackChan 公式ファームウェアを、Windows 11上でビルドし、本番のM5Stack版 StackChan実機へ書き込み、起動確認まで行います。
追記：その後の再検証で、StackChan Worldアプリとの初回連携やAvatarモードについては、M5Burner公式版と自前ビルド版で挙動が異なる場合があることを確認しました。詳細は記事末尾の追記にまとめます。

最終的に以下まで成功しました。

ビルド成果物の生成
C:\m5sc\firmware\build\stack-chan.bin

本番機への書き込み
idf.py -p COM12 flash

本番機のシリアルモニターでの起動確認
idf.py -p COM12 monitor

ビルドログ末尾では、以下まで到達しています。

Generated C:/m5sc/firmware/build/stack-chan.bin

Project build complete. To flash, run:
 idf.py flash

検証範囲

この記事で確認した環境は以下です。

OS: Windows 11
Shell: PowerShell 7.4.7
ESP-IDF: v5.5.4
Target: esp32s3
Python: Python 3.13.1
Repository: https://github.com/m5stack/StackChan.git
作業ディレクトリ: C:\m5sc\firmware
ESP-IDF path: C:\esp\v5.5.4\esp-idf
ESP-IDF tools path: C:\Espressif\tools
本番機: M5Stack版 StackChan
本番機COMポート: COM12

M5Stack版 StackChan公式FW側のアプリバージョンは、起動ログ上では以下でした。

App version: 1.4.1

一方、内部で利用している `xiaozhi-esp32` は、`v2.2.4` をベースに、StackChan側の `xiaozhi-esp32.patch` を適用した状態です。
そのため、`git describe` では `v2.2.4-dirty` と表示されます。

ESP-IDF v5.5.1 / v5.5.2 / v5.5.3 や、Python 3.11 / 3.12 では未検証です。

フェーズ1：ビルド環境の準備

1. 重要な原因と対策

1.1 問題

最初は python fetch_repos.py 実行時に、以下のようなエラーが出ていました。

xiaozhi-esp32.patch cannot be applied cleanly
patch does not apply

実際には、以下のように i2c_device.cc 周辺でパッチ適用に失敗していました。

error: patch failed: main/boards/common/i2c_device.cc:32
error: main/boards/common/i2c_device.cc: patch does not apply
Patch C:\m5sc\firmware\patches/xiaozhi-esp32.patch cannot be applied cleanly to C:\m5sc\firmware\xiaozhi-esp32, skipped.

その状態で idf.py build を実行すると、以下で停止しました。

fatal error: expression_emote.h: No such file or directory
#include "expression_emote.h"

つまり、xiaozhi-esp32.patch が正常に当たらなかった結果、本来コメントアウトされるはずの expression_emote.h のincludeが残り、ビルドに失敗していました。

1.2 原因

原因は、Windows Git の core.autocrlf=true により、パッチ適用対象ファイルの改行が変わり、xiaozhi-esp32.patch が当たらなかったことです。

Git for Windows の標準設定では core.autocrlf=true になっていることがあり、Windows環境ではこの種のpatch適用失敗が起きる場合があります。

1.3 対策

core.autocrlf=false にしてから、C:\m5sc を丸ごと再cloneしました。

今回の環境では、xiaozhi-esp32 だけ削除して再取得する方法では不十分でした。

最終的には、StackChan本体も含めて core.autocrlf=false 状態で再cloneしたことで、パッチが正常適用されました。

成功時のログには以下が出ました。

Applied patch C:\m5sc\firmware\patches/xiaozhi-esp32.patch to C:\m5sc\firmware\xiaozhi-esp32

具体的な手順は、次の章にまとめます。

2. クリーンにやり直す手順

2.1 Git改行設定を変更

PowerShellで実行します。

cd C:\

git config --global core.autocrlf false
git config --global --get core.autocrlf

期待値：

false

注意：git config --global core.autocrlf false は、他のGitリポジトリにも影響します。

ただし今回の fetch_repos.py は、内部で xiaozhi-esp32 など複数の依存リポジトリをcloneするため、親リポジトリだけの --local 設定では十分でない可能性があります。

そのため、この記事では再現性を優先し、--global で core.autocrlf=false を設定しました。

他のプロジェクトへの影響が気になる場合は、作業後に設定を戻すか、別のGit環境で実行してください。

2.2 既存フォルダを退避

既存の C:\m5sc がある場合は退避します。

if (Test-Path C:\m5sc) {
  Rename-Item C:\m5sc C:\m5sc_autocrlf_old
}

日付付きで残す場合は、以下のようにします。

if (Test-Path C:\m5sc) {
  Rename-Item C:\m5sc C:\m5sc_autocrlf_old_20260516
}

C:\m5sc を丸ごと退避するため、既存の build フォルダや生成済みバイナリも一緒に退避されます。

本記事の手順でビルド・書き込み・動作確認まで完了して問題がなければ、退避した古いフォルダは削除して構いません。

2.3 再clone

cd C:\

git -c core.autocrlf=false clone https://github.com/m5stack/StackChan.git C:\m5sc
cd C:\m5sc\firmware

3. PowerShell再起動後のESP-IDF環境設定

PC再起動後、または新しいPowerShellを開いた後は、毎回以下を実行します。

cd C:\m5sc\firmware

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force

$py = "C:\Users\<YourUserName>\AppData\Local\Programs\Python\Python313"

$env:PATH = ($env:PATH -split ';' | Where-Object {
  $_ -notmatch '\\.platformio\\penv' -and
  $_ -notmatch '\\python_env\\'
}) -join ';'

$env:PATH = "$py;$py\Scripts;$env:PATH"

$env:IDF_TOOLS_PATH="C:\Espressif\tools"
$env:IDF_PATH="C:\esp\v5.5.4\esp-idf"

. C:\esp\v5.5.4\esp-idf\export.ps1

<YourUserName> は、自分のWindowsユーザー名に置き換えてください。

例：

$py = "C:\Users\Taro\AppData\Local\Programs\Python\Python313"

確認：

idf.py --version
pwd

期待値：

ESP-IDF v5.5.4
C:\m5sc\firmware

このPATH操作では、PlatformIOのPython仮想環境や、過去に読み込まれたESP-IDFの python_env を一度PATHから外しています。

今回の環境では、PlatformIOのPythonが python として先に見えてしまい、ESP-IDFの export.ps1 が別のPython仮想環境を探しに行って失敗しました。

PlatformIOを入れていないPCでは、この問題は起きない可能性があります。

4. 依存リポジトリ取得

python fetch_repos.py

成功時は、xiaozhi-esp32.patch が正常適用されます。

Applied patch C:\m5sc\firmware\patches\xiaozhi-esp32.patch to C:\m5sc\firmware\xiaozhi-esp32

途中で以下のような trailing whitespace 警告が出る場合があります。

trailing whitespace.
warning: 1 line adds whitespace errors.

これは今回のビルド停止要因ではありませんでした。

5. パッチ適用検証

expression_emote.h がコメントアウトされていることを確認します。

Select-String -Path .\xiaozhi-esp32\main\assets.cc -Pattern "expression_emote|emote_display"

期待値：

xiaozhi-esp32\main\assets.cc:6:// #include "emote_display.h"
xiaozhi-esp32\main\assets.cc:7:// #include "expression_emote.h"

さらに、EmoteDisplay 関連処理もコメントアウトされていることを確認しました。

この状態になっていれば、xiaozhi-esp32.patch が正しく当たっていると判断できます。

6. ターゲット設定

初回のみ実行します。

$env:IDF_TARGET="esp32s3"
idf.py set-target esp32s3

成功時は、以下が出ます。

Build files have been written to: C:/m5sc/firmware/build

実際に set-target esp32s3 後、CMake設定は正常完了しています。

7. ビルド

idf.py build

ビルド中に以下のような warning は出ましたが、今回の環境ではビルド停止要因ではありませんでした。

_IO redefined
unused variable
configTASKLIST_INCLUDE_COREID

これらは今回のビルド成功を妨げるものではなかったため、本記事では追加対処せずに進めました。

最終的に以下が出て成功しました。

Generated C:/m5sc/firmware/build/stack-chan.bin

Project build complete. To flash, run:
 idf.py flash

8. ビルド成功後の成果物

主な生成物：

C:\m5sc\firmware\build\bootloader\bootloader.bin
C:\m5sc\firmware\build\partition_table\partition-table.bin
C:\m5sc\firmware\build\ota_data_initial.bin
C:\m5sc\firmware\build\stack-chan.bin
C:\m5sc\firmware\build\generated_assets.bin

ログ上では以下も確認済みです。

stack-chan.bin binary size 0x39a220 bytes.
Smallest app partition is 0x4f0000 bytes.
0x155de0 bytes (27%) free.

generated_assets.bin は、フォント、絵文字、起動用アセット、WakeNetモデルなどをまとめたアセット用バイナリです。

書き込み時には、0xa00000 の assets パーティションへ書き込まれます。

9. 注意点

9.1 idf.py update-dependencies は実行しない

ビルド中に以下のような案内が出ます。

Following dependencies have new versions available
Consider running "idf.py update-dependencies"

今回は公式ファームの再現ビルドが目的なので、実行しません。

依存コンポーネントを更新すると、公式FWが想定しているバージョンとの整合が崩れ、別のビルドエラーにつながる可能性があります。

9.2 core.autocrlf=false は維持する

このビルドでは、xiaozhi-esp32.patch の適用に core.autocrlf=false が重要でした。

git config --global core.autocrlf false

9.3 新しいPowerShellでは毎回ESP-IDF環境を読み込む

PC再起動後やPowerShellを開き直した後は、idf.py が使えない、またはPython仮想環境を見失うことがあります。

その場合は、必ず「3. PowerShell再起動後のESP-IDF環境設定」を再実行してください。

フェーズ2：実機書き込み

10. COMポート確認

M5Stack版 StackChanをUSBでPCに接続し、デバイスマネージャーでCOMポートを確認します。

本番のM5Stack版 StackChanは、以下として認識されました。

USB シリアル デバイス (COM12)

Bluetooth経由のCOMポートではなく、USBシリアルデバイスのCOM番号を使います。

PowerShellで確認する場合：

[System.IO.Ports.SerialPort]::GetPortNames()

11. 書き込み実行

ESP-IDF環境を読み込んだPowerShellで、作業ディレクトリに移動します。

cd C:\m5sc\firmware

本番機のCOMポートは COM12 だったため、以下で書き込みを実行しました。

idf.py -p COM12 flash

COM番号は環境によって変わるため、別環境では実際に表示されたCOM番号に置き換えてください。

例：

idf.py -p COM10 flash
idf.py -p COM11 flash
idf.py -p COM12 flash

12. 書き込み対象

書き込み時には、以下がFlashへ書き込まれました。

0x0       build\bootloader\bootloader.bin
0x8000    build\partition_table\partition-table.bin
0xd000    build\ota_data_initial.bin
0x20000   build\stack-chan.bin
0xa00000  build\generated_assets.bin

実際の esptool.py ログでは表示順が異なる場合がありますが、上記はFlashアドレス昇順に並べたものです。

実際のログでは、以下のように esptool.py が実行されました。

esptool.py --chip esp32s3 -p COM12 -b 460800 ... write_flash ...

本番機のMACアドレスは、ログ上では以下のように認識されます。

MAC: 44:1b:f6:**:**:**

公開記事に載せる場合は、実機固有値のため伏字にすることをおすすめします。

13. 書き込み成功ログ

書き込みは正常に完了しました。

成功時のログ末尾は以下です。

Hash of data verified.

Leaving...
Hard resetting via RTS pin...
Done

この表示が出ていれば、Flash書き込みと検証は成功しています。

ただし、この時点では「書き込み成功」であり、「アプリが正常起動した」ことまではまだ確認していません。

起動確認は、次のシリアルモニターで行います。

今回の到達状態：

ビルド成功
COM12認識
本番機へのflash成功
Hard reset完了

フェーズ3：本番機での起動確認

14. シリアルモニター起動

書き込み後、シリアルログを確認するため、以下を実行しました。

idf.py -p COM12 monitor

monitorを終了する場合：

Ctrl + ]

15. 起動成功の確認ポイント

ログ上で、以下が確認できました。

Project name:     stack-chan
App version:      1.4.1
ESP-IDF:          v5.5.4

また、以下のログにより、アプリ本体が起動して app_main() まで進んでいることも確認できました。

main_task: Calling app_main()
[HAL] init
[HAL] xiaozhi board init

本番機のボード情報として、以下のような情報が表示されます。

UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SKU=m5stack-stack-chan

PSRAMも認識されています。

Found 8MB PSRAM device

これにより、書き込んだM5Stack版 StackChan公式FWが、本番機で正常に起動していることを確認できました。

16. 本番機で正常に初期化された項目

ログ上では、以下の初期化が正常に進みました。

LCD / LVGL 初期化 OK
Camera init success
FT6336 タッチ初期化 OK
Si12T ヘッドタッチ初期化 OK
PY32IOExpander init done
RTC PCF8563 init ok
BMI270 init ok
Servo ID 1 / ID 2 読み込み OK
Launcher 起動 OK
BLE config server 起動 OK
Wi-Fi STA 初期化 OK

特に以下のログが出ており、初回セットアップ処理まで到達しています。

[Setup-Startup] start servo test
[Setup-Startup] start wifi setup
[HAL-BLE] start app config server

17. 表示された識別情報

今回の本番機起動ログでは、以下のような識別情報が表示されました。

UUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Factory MAC: 44:1b:f6:**:**:**
BLE MAC: 44:1b:f6:**:**:**

実際のログには実機固有のUUIDやMACアドレスが表示されます。

公開記事に載せる場合は、実機特定につながる情報のため、伏字またはダミー値への置換をおすすめします。

18. 本番機での起動確認結果

本番のM5Stack版 StackChanでは、起動ログ上で以下が正常に初期化されました。

Camera init success
HAL-IOE init done
BMI270 init ok
Servo ID 1 / ID 2 読み込み OK
BLE config server 起動 OK
Wi-Fi STA 初期化 OK

別CoreS3で確認した際には、以下のようなエラーが出ていました。

StackChanCamera: open /dev/video2 failed
[HAL-IOE] init timeout
BMI270 init failed

しかし、本番のM5Stack版 StackChanではこれらは発生しませんでした。

M5Stack版 StackChan本体には、カメラ、IO Expander、IMU、サーボなどが搭載されています。一方、別CoreS3単体では同じ周辺ハードウェア構成ではないため、これらの初期化エラーはハードウェア構成差によるものと考えられます。

現時点の判断：

ビルド成功
書き込み成功
本番M5Stack版 StackChanでファーム起動成功
各種主要デバイス初期化成功
初期設定待ちまで到達

これで、Windows 11環境におけるM5Stack版 StackChan公式FWの ビルド・書き込み・本番機起動確認 まで完了しました。

FAQ

core.autocrlf=false にすると他のプロジェクトに影響しますか？

--global で設定すると、他のGitリポジトリにも影響します。

今回の fetch_repos.py は内部で依存リポジトリをcloneするため、この記事では再現性を優先して --global を使いました。

他のプロジェクトへの影響が気になる場合は、作業後に設定を戻すか、別環境で実行してください。

xiaozhi-esp32 だけ削除して再取得すればよいですか？

今回の環境では、それだけでは不十分でした。

core.autocrlf=false にしたうえで、C:\m5sc 全体を再cloneすることで、xiaozhi-esp32.patch が正常に当たりました。

ESP-IDF v5.5.4でないと駄目ですか？

この記事では、ESP-IDF v5.5.4でビルド成功を確認しました。

v5.5.1 / v5.5.2 / v5.5.3 では未検証です。

Python 3.13.1でないと駄目ですか？

この記事では、Python 3.13.1で確認しました。

Python 3.11 / 3.12 では未検証です。

PlatformIOを入れていないPCでも同じPATH対策が必要ですか？

PlatformIOを入れていないPCでは、PlatformIOのPythonが先に見える問題は起きない可能性があります。

ただし、ESP-IDFの export.ps1 が別のPython環境を見に行って失敗する場合は、この記事と同じようにPythonのPATHを確認してください。

idf.py update-dependencies は実行してよいですか？

この記事では実行しません。

依存コンポーネントを更新すると、公式FWが想定しているバージョンとの整合が崩れ、別のビルドエラーにつながる可能性があります。

App version: 1.4.1 と xiaozhi-esp32 v2.2.4 は何が違いますか？

App version: 1.4.1 は、M5Stack版 StackChan公式FW側のアプリバージョンです。

一方、xiaozhi-esp32 は、内部で利用している依存リポジトリです。

今回の検証では、xiaozhi-esp32 v2.2.4 をベースに、StackChan側の xiaozhi-esp32.patch を適用した状態でビルドしています。

そのため、git describe では v2.2.4-dirty と表示されます。

App version: 1.4.1 と xiaozhi-esp32 v2.2.4 は別のバージョン体系なので、混同しないように注意してください。

まとめ

Windows 11でM5Stack版 StackChan公式FWをビルドする際、xiaozhi-esp32.patch が当たらず、expression_emote.h: No such file or directory で止まる場合があります。

今回の環境では、原因は Git の core.autocrlf=true による改行変換でした。

最終的には、以下の流れで解決しました。

git config --global core.autocrlf false
↓
C:\m5sc を丸ごと再clone
↓
python fetch_repos.py
↓
xiaozhi-esp32.patch が正常適用
↓
idf.py build
↓
idf.py -p COM12 flash
↓
idf.py -p COM12 monitor
↓
起動成功・初期セットアップ画面到達

これにより、本番のM5Stack版 StackChanで、公式FWのビルド、書き込み、起動確認まで完了しました。

追記：StackChan Worldアプリ連携とAvatarモードについて

この記事の手順で自前ビルドしたファームウェアは、ビルド、書き込み、実機起動までは確認できました。

その後、StackChan Worldアプリとの連携も試したところ、初回追加時に `Failed to process device data.` が表示される場合がありました。

ただし、別フォルダへ新規cloneし直し、`core.autocrlf=false` の状態で `fetch_repos.py` を実行して再ビルドした版では、初回接続時にエラー表示が出たあとでも、StackChan本体のリセットボタンで再起動すると、初期設定画面には戻らず通常メニューへ進むことを確認しました。

そのため、`Failed to process device data.` が表示された場合でも、完全に失敗しているとは限りません。まずはStackChan本体をリセットし、再起動後に通常メニューへ進むか確認してください。

一方で、Avatarモードについては動作しませんでした(5/17時点)。

自前ビルド版では、Avatarモード起動時に `Connect to server Failed` が繰り返し表示されることを確認しました。シリアルログ上ではWi-Fi接続自体は成功していましたが、その後、Avatarモードが `localhost:3000` へ接続しようとして失敗していました。ソースからビルドする場合は、今後の最新ソース待ちのようです。この記事の手順は、あくまで「GitHub公開ソースからビルドし、実機で起動するところまでの検証記録」として参照してください。

参考リンク

M5Stack StackChan 公式リポジトリ: https://github.com/m5stack/StackChan
xiaozhi-esp32: https://github.com/78/xiaozhi-esp32
ESP-IDF Programming Guide: https://docs.espressif.com/projects/esp-idf/
fetch_repos.py fails if git autocrlf is true / Issue #62:
https://github.com/m5stack/StackChan/issues/62

M5Stack版StackChan：公式FWをWindows 11で動かすまでの手順— v1.4.1 / 2026年5月17日時点のビルド記録

M5Stack版 StackChan - ｽﾀｯｸﾁｬﾝを変更する

何はともあれ、元に戻す方法を確認

本題：この記事で解決すること

目的

検証範囲

フェーズ1：ビルド環境の準備

1. 重要な原因と対策

2. クリーンにやり直す手順

3. PowerShell再起動後のESP-IDF環境設定

4. 依存リポジトリ取得

5. パッチ適用検証

6. ターゲット設定

7. ビルド

8. ビルド成功後の成果物

9. 注意点

フェーズ2：実機書き込み

10. COMポート確認

11. 書き込み実行

12. 書き込み対象

13. 書き込み成功ログ

フェーズ3：本番機での起動確認

14. シリアルモニター起動

15. 起動成功の確認ポイント

16. 本番機で正常に初期化された項目

17. 表示された識別情報

18. 本番機での起動確認結果

FAQ

core.autocrlf=false にすると他のプロジェクトに影響しますか？

xiaozhi-esp32 だけ削除して再取得すればよいですか？

ESP-IDF v5.5.4でないと駄目ですか？

Python 3.13.1でないと駄目ですか？

PlatformIOを入れていないPCでも同じPATH対策が必要ですか？

idf.py update-dependencies は実行してよいですか？

App version: 1.4.1 と xiaozhi-esp32 v2.2.4 は何が違いますか？

まとめ

追記：StackChan Worldアプリ連携とAvatarモードについて

参考リンク

いいなと思ったら応援しよう！