
Cursor × WSL2 × Rust で ESP32-C3 開発環境を作る(M5Stamp C3U Mate でハマった点も整理)
技術記事っぽいのもnoteに投稿してみる挑戦。
M5Stamp C3U Mate でハマった点も整理
Windows を普段使いにしつつ、Cursor でコードを書いて、WSL2 でビルドして、ESP32-C3 を Rust で触る。
今回はそんな構成を作ったときのメモです。
実機として使ったのは、M5Stack の M5Stamp C3U Mate。
SoC は ESP32-C3 です。
このボード、小さくて扱いやすそうに見えるし、実際かなり魅力的です。
ただ、いわゆる「USB-UART 付きの普通の DevKit」とは USB 周りの勝手が少し違っていて、同じ ESP32-C3 でも思ったより詰まり方が変わると感じました。
この記事では、次の3つをまとめます。
Windows / WSL2 / Cursor / Rust で ESP32-C3 開発環境を作る手順
ファームウェアを Hello world だけの最小版 と LED 版 の2段階に分けて整理すること
usbipd、espflash、App Descriptor、efuse まわりでハマった点と、その対策
今回やりたかったこと
やりたかったこと自体はシンプルです。
Cursor でコードを書く
WSL2 上で Rust と ESP 向けツールを動かす
ESP32-C3 向けにビルドして実機に書き込む
シリアルで起動ログを確認する
ゴールも2段階に分けると分かりやすいです。
まずは、シリアルに一行でもログが出ればOKの「Hello world 最小版」。
そのあとで、内蔵 LED やボタンまで使う「LED 版」 に広げる、という順番です。
この順に分けて考えると、
「環境構築で詰まっているのか」
「アプリを広げたことで詰まっているのか」
を切り分けやすくなります。
今回の構成
今回の構成はこうです。開発環境は、
Windows
WSL2
Cursor
Rust
espup
espflash
実機は、
M5Stack M5Stamp C3U Mate
SoC は ESP32-C3
です。
全体としてはかなり素直な構成に見えますが、実際にやってみると、ポイントになるのは WSL2 から USB デバイスをどう扱うか と、ESP32-C3 側へどう正しい形式のイメージを書き込むか の2つでした。
なぜこの構成にしたのか
理由は単純です。
まず、Cursor で開発したかった。
ESP32 開発でも、コードの検索、補完、修正のしやすさは重要なので、エディタ体験は落としたくありませんでした。
次に、Rust や ESP 系の CLI ツールは WSL2 に寄せたかった。
Windows ネイティブでも不可能ではないですが、Linux 前提の手順や情報が多いので、WSL2 にまとめた方が整理しやすいです。
そして、ESP32-C3 を Rust で触りたかった。
ESP32-C3 は RISC-V 系なので、Rust でも比較的入りやすい印象があります。
先に知っておいた方がいいこと
今回使った M5Stamp C3U Mate は、一般的な「USB-UART 変換チップ付きの開発ボード」と少し違います。
つまり、
「ESP32-C3 のボードだからどれも同じように扱えるだろう」
と思って進めると、意外とハマります。実際少しハマりました。
感覚としては、
普通の DevKit は USB-UART で比較的素直
M5Stamp C3U Mate は内蔵 USB 系なので少しクセがある
という違いがありました。
この差を意識しておくだけで、後で「あれ、なんでこれだけ挙動が違うんだろう」と悩む時間を減らせます。
環境構築の流れ
全体の流れは次のとおりです。
まず Windows 側で、
WSL2 を使えるようにする
usbipd-win を入れる(これで、USBデバイスがWSL上で認識できるようになるのです!)
Cursor を入れる
次に WSL2 側で、
必要パッケージを入れる
Rust を入れる
espup を入れる
espflash を入れる
そのあと、
Rust プロジェクトを作る
ESP32-C3 向けにビルドする
Windows 側で USB を WSL2 に共有する
espflash で書き込む
モニタでログを見る
という順で進めました。
Windows 側の準備
まずは WSL2 を使える状態にします。
Ubuntu を入れて、WSL2 を既定にしておきます。
次に、USB デバイスを WSL2 に渡すために usbipd-win を使います。
今回のように ESP32 系の実機を WSL2 側で扱う場合、ここはかなり重要でした。
参考
管理者権限の PowerShell で、まずデバイス一覧を確認します。
usbipd list
対象デバイスの BusId を確認したら、最初に必要なのは attach ではなく bind です。
usbipd bind --busid <BusId>
そのあとで WSL にアタッチします。
usbipd attach --wsl --busid <BusId>
この順番を知らないと、
「デバイスは見えているのに attach できない」
というところで一度止まります。
Cursor は通常どおりインストールすれば問題ありません。
プロジェクトは WSL 側のディレクトリ に置いて、Cursor から WSL のフォルダを開く形にすると、パスやシェルまわりが素直でした。
WSL2 側の準備
WSL2 側では、まずビルドに必要なパッケージを入れます。
sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev
続いて Rust を入れます。
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
そのあと、ESP 向けのツールチェーンとして espup を入れます。
cargo install espup
espup install
インストール後は、espup が案内する環境変数の読み込みも必要です。たとえば次のような形です。
. "$HOME/export-esp.sh"
毎回手で読むのが面倒なら、~/.bashrc に追加しておくと楽です。
書き込みとモニタには espflash を使います。
cargo install espflash
ここまでで、リポジトリ直下で cargo build が通るようになれば、ツールチェーン側はだいたい揃っています。
プロジェクト側の設定
今回のプロジェクトでは、.cargo/config.toml 側でターゲットを riscv32imc-unknown-none-elf に固定し、build-std = ["core"] を使う構成にしています。
加えて、rust-toolchain.toml では stable チャンネル、rust-src、そして riscv32imc-unknown-none-elf を指定しています。
つまり、プロジェクト側としては、
どのターゲット向けにビルドするか
no_std 系で必要な rust-src
cargo run 時の runner
あたりをあらかじめ整理しておくと、後で迷いにくくなります。
実機接続から書き込みまで
WSL2 側でデバイスが見えるようになったら、まずシリアルデバイスを確認します。
ls -l /dev/ttyACM*
その上でプロジェクトをビルドします。
cd /path/to/m5stamp_c3u_sample
cargo build
書き込みは espflash で行います。
espflash flash -p /dev/ttyACM0 --monitor \
target/riscv32imc-unknown-none-elf/debug/m5stamp_c3u_sample
挙動が怪しいときや、差分書き込みではなくちゃんと全体を書き直したいときは、--no-skip を付けて切り分けます。
espflash flash -p /dev/ttyACM0 --monitor --no-skip \
target/riscv32imc-unknown-none-elf/debug/m5stamp_c3u_sample
ファームウェアは2段階に分けると楽
今回、整理していていちばん大事だと感じたのはここです。
ファームウェアは最初から全部盛りにせず、Hello world だけの最小版 と LED 版 に明示的に分けた方がいいです。
そうすると、
環境が通っているか
実機との接続が通っているか
アプリの拡張で壊れているのか
を段階ごとに確認できます。
Hello world だけの最小版
最初の段階では、目的をかなり絞ります。
やりたいのは、
ツールチェーンが通る
USB が通る
書き込みが通る
ブートする
シリアルに一行出る
これだけです。
つまり、ハード依存の機能はまだ触らなくてよくて、
最小の main で Hello world! が一行でも見えれば合格です。
イメージとしてはこういう感じです。
#![no_std]
#![no_main]
use esp_backtrace as _;
use esp_hal::prelude::*;
#[entry]
fn main() -> ! {
let _peripherals = esp_hal::init(esp_hal::Config::default());
esp_println::println!("Hello world!");
loop {}
}
ただし今回の構成では、App Descriptor まわりの整合性 が必要でした。
なので、見た目上は最小に見えても、実際には
app_desc.rs
ld/rodata.x
build.rs による rodata パッチ
のような土台が入っていた方が安全でした。
ここを省いて「最小だからこれだけでいいだろう」と進めると、後でブート時にハマります。
LED 版
Hello world 版で、環境と起動パイプラインが通ったことを確認できたら、次に LED 版へ進みます。
こちらは M5Stamp C3U Mate らしい機能をちゃんと触る段階です。
具体的には、
内蔵 SK6812
ボタン入力
周期性ログ
を入れます。
今回の構成では、
src/app_desc.rs
ld/rodata.x
build.rs
src/sk6812.rs
src/main.rs
が主なポイントになりました。
動作としては、
GPIO9 をボタン入力に使う
GPIO2 と RMT で内蔵 SK6812 を制御する
ボタン押下で点滅モードを切り替える
1秒ごとに状態ログを出す
という形です。
つまり、Hello world 版が「環境が通った確認」だとすると、LED 版は「ボード固有の機能を使う段階」です。
Git の運用としても、
まずは Hello world 版のコミットを切って、その上に LED 版を積む
という形にするとかなり分かりやすいと思います。
実際にハマったポイント
今回ハマったポイントをまとめると、主に3つです。
まず、usbipd は attach の前に bind が必要だったこと。
ここを知らないと、Windows 側でデバイスが見えているのに先に進めません。
次に、espflash ではポートを明示する必要があったこと。
-p /dev/ttyACM0 の形で書かないと、思った通りに解釈されませんでした。
そしていちばん大きかったのが、App Descriptor とその配置 です。
これが無い、あるいは無視して進めると、あとで efuse blk rev まわりのエラーになってブートに失敗しました。
つまり、今回の環境では
「書ければいい」ではなく、「正しいアプリイメージとして書けること」が重要だった
ということです。
まとめ
今回の構成は、Windows をホストにしつつ、
WSL2
Cursor
Rust
ESP32-C3
M5Stamp C3U Mate
を組み合わせて進めるものです。
整理してみると、
環境構築は Windows 側の USB 共有 と WSL 側のツールチェーン
ファーム側は Hello world 最小版 と LED 版
ハマりどころは usbipd、espflash、App Descriptor
というふうに分けて考えると分かりやすかったです。
M5Stamp C3U Mate は小さくて魅力的なボードですが、
最初の開発ボードとしては少しクセがあります。
ただ、そのクセを把握した上で進めれば、
Cursor × WSL2 × Rust で ESP32-C3 を触る構成自体は十分実用的 だと感じました。
同じような構成で試す人の参考になればうれしいです。