電子工作素人によるスタックチャン製作記１１（M5StackChanファーム改造準備編）

本記事は、M5StackChan の firmware を Windows 環境でビルドするために必要となる ESP-IDF 開発環境のセットアップ手順をまとめたものです。
自分で環境作るときにいろいろハマったので備忘録もかねて恥ずかしいけどトラシュー情報も記載。

ファームウェアバージョン1.2.4, 1.2.6, 1.3.0, 1.4.1 で検証。

M5StackChanとは

ｽｰﾊﾟｰｶﾜｲｲ手乗りロボットであるｽﾀｯｸﾁｬﾝをM5Stackが公式にキットとして販売したもの。

公式サイト
https://docs.m5stack.com/ja/StackChan

本家のGitHubリポジトリ
https://github.com/m5stack/StackChan

• firmware : M5StackChan 本体のファームウェア

• remote : Joyコントローラー用のアプリ

• app : スマートフォン用のアプリ

• server : アプリと StackChan 本体をつなぎ、ユーザーデータや動作データを一括管理するシステム

このうち、M5StackChan のファームウェアやリモートコントローラーのコードを改造してオリジナルな機能や動きを実装できます。

前提条件

1. VS Code 拡張機能のインストール

1. VS Code を起動

2. `Ctrl+Shift+X` で拡張機能パネルを開く

3. 「ESP-IDF」で検索

4. Espressif IDF (`espressif.esp-idf-extension`) をインストール

2. EIM（Espressif Installation Manager）のインストール

ESP-IDF 本体のインストールには EIM というツールを使用します。

インストール方法

PowerShell を開いて以下を実行：

winget install Espressif.EIM

3. ESP-IDF のインストール（EIM を使用）

インストールした EIM の起動

以下のいずれかの方法で起動：

• スタートメニュー → 「eim」で検索 → クリック

EIM での操作手順

1. 「New Installation」 → 「Start Installation」 をクリック

2. 「Custom Installation」 を選択（Easy Installation ではバージョン指定ができないため）

Custom Installation の設定値

1. 「Start Installation」 をクリック

2. インストール完了まで待つ（10〜30分、ネット速度次第）

3. 「Installation Complete」 が表示されれば成功

インストール後のディレクトリ構造（例）

C:\esp\
  └── v5.5.4\
      └── esp-idf\          ← IDF_PATH

C:\Espressif\
  └── tools\               ← IDF_TOOLS_PATH
      ├── cmake\
      ├── ninja\
      ├── xtensa-esp-elf\   ← コンパイラ
      ├── python\v5.5.4\venv\  ← Python 仮想環境
      └── ...

4. VS Code で ESP-IDF を認識させる

バージョン選択

1. VS Code で ファームウェアプロジェクトのフォルダを開く

2. `Ctrl+Shift+P` → `ESP-IDF: Select Current ESP-IDF Version`

3. 一覧から v5.5.4 を選択

動作確認

`Ctrl+Shift+P` → `ESP-IDF: Doctor Command` を実行し、以下を確認：

• `ESP-IDF Path` が `C:\esp\v5.5.4\esp-idf` を指している

• `ESP-IDF version` が `5.5.4` である

• `Python requirements are satisfied.` と表示される

• ツールチェーンの各パスが `Access: true` になっている

5. 依存リポジトリの取得

本ファームウェアは以下の外部リポジトリに依存しています（`repos.json` で定義）：

取得手順

1. `Ctrl+Shift+P` → `ESP-IDF: Open ESP-IDF Terminal` でESP-IDF用のターミナルを開く

   1. ターミナルの起動に失敗することがありますが、その場合 `バージョン選択` からのステップを何回かやり直すと起動できるようになります（VS Codeの内部的な状態管理の問題かな？）

2. ファームウェアのルートディレクトリに移動して下記コマンドを実行。完了すると `components/` と `xiaozhi-esp32/` ディレクトリが生成されます。

python fetch_repos.py

6. ビルド

ターゲット設定とビルド（idf.pyで実施する場合）

ESP-IDF Terminal で以下を実行：

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

ビルドに失敗した場合

もし idf.py build で次のエラーが出た場合は A-Utaさんの記事に対処方が記載されていますので、そちらもご覧ください。

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

ビルド成功の確認

以下のメッセージが表示されれば成功（1.3.0ではいくつかwarningやnoteなどが出るようですがビルド自体は成功とみなしてOKの様子）

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

`build/stack-chan.bin` が生成されていることを確認。

補足：VS Code GUI からビルドする場合の手順

1. `Ctrl+Shift+P` → `ESP-IDF: Set Espressif Device Target` → `esp32s3`

2. `Ctrl+Shift+P` → `ESP-IDF: Build your Project`

7. フラッシュ（書き込み）

M5Stack CoreS3 を USB で接続し、ESP-IDF Terminal で：

idf.py flash

ポートを指定する場合：

idf.py -p COM3 flash

シリアルモニターも同時に起動する場合：

idf.py flash monitor

トラブルシューティング

だいたい困ったらAIに聞いて解決する、でいけるんですがどういう問題に遭遇したのかという情報共有として書いておこうと思います。

`idf.py: command not found`

• 遭遇するタイミング: 手順 5, 6, 7 などで `idf.py` コマンドを実行しようとした際

• 原因: 通常の PowerShell ターミナル（または Command Prompt）を使用している。

• 対処: `Ctrl+Shift+P` → `ESP-IDF: Open ESP-IDF Terminal` で ESP-IDF 用ターミナルを開いてください。このターミナルは `IDF_PATH`、`PATH` 等の環境変数を自動的にセットします。

`Target 'esp32s3' is not consistent with target 'esp32' in the environment`

• 遭遇するタイミング: 手順 6 の `idf.py set-target esp32s3` 実行時

• 原因: VS Code 拡張が環境変数 `IDF_TARGET=esp32` をセットしている。

• 対処: ビルド前に環境変数を上書きしてからコマンドを実行してください：

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

`[WinError 3] 指定されたパスが見つかりません`（managed_components 関連）

• 遭遇するタイミング: 手順 6 の `idf.py build` 実行中（依存コンポーネントのダウンロード時）

• 原因: Windows のデフォルトのパス長制限（260文字）に引っかかっている。このプロジェクトは 60 以上のコンポーネントに依存しており、`managed_components/` 配下のパスが非常に長くなります。

• 対処:

  1. 管理者 PowerShell でWindows の長いパスサポートを有効にする下記コマンドを実行する。それでも解決しない場合は、プロジェクトを短いパスに移動する（次項参照）。

 ```powershell
 reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f
 ```

`CreateProcess: The parameter is incorrect. (is the command line too long?)`

• 遭遇するタイミング: 手順 6 の `idf.py build` 実行時（リンクフェーズなど）

• 原因: コンパイラに渡されるコマンドライン（大量の `-I` インクルードパス）が Windows の `CreateProcess` API の上限（32,767文字）を超えている。これはプロジェクトのベースパスが長い場合に発生します。長いパスの有効化（`LongPathsEnabled`）では解決しません。

• 対処: プロジェクトを短いパスに移動する。

# 例: C:\work\sc\ に移動
mkdir C:\work\sc
xcopy "C:\Users\XXXXX\Documents\work\m5stackchan\m5stackchan-firmware\*" "C:\work\sc\" /E /I /H

移動後はクリーンビルドが必要：

cd C:\work\sc\m5stackchan-firmware
Remove-Item -Recurse -Force .\build -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force .\managed_components -ErrorAction SilentlyContinue
$env:IDF_TARGET="esp32s3"
idf.py set-target esp32s3
idf.py build

`.component_hash or CHECKSUMS.json does not exist`（esp-dsp 等）

• 遭遇するタイミング: 手順 6 の `idf.py build` 実行時

• 原因: 前回のビルドでパスエラーが起きた際に、managed_components が中途半端にダウンロードされて壊れた状態で残っている。

• 対処: managed_components と build を削除して再ビルド：

Remove-Item -Recurse -Force .\managed_components
Remove-Item -Recurse -Force .\build
idf.py set-target esp32s3
idf.py build

`Directory doesn't seem to be a CMake build directory. Refusing to automatically delete files.`

• 遭遇するタイミング: 手順 6 の `idf.py build` 実行時やクリーン時

• 原因: 前回の不完全なビルドで build ディレクトリが壊れている。

• 対処: 手動で build ディレクトリを削除：

Remove-Item -Recurse -Force .\build

参考リンク

• ESP-IDF v5.5.4 ドキュメント

• ESP-IDF VS Code 拡張ドキュメント

• EIM (Espressif Installation Manager)

• ESP-IDF Windows セットアップ公式ガイド