メインコンテンツへスキップ
見出し画像

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 を触る構成自体は十分実用的 だと感じました。

    同じような構成で試す人の参考になればうれしいです。

     
     
    コーヒーのなんか作る 余裕を持つために「やらなきゃいけないこと」をやらなくてもよくするモノを作る! コーヒーで一息つく!モノづくりしてます。 エンジニアっぽいことをしています。 Simple is Best

    あなたへのおすすめ