Skip to content

getting-started-wsl2_ja.md

Latest commit

 

History

History
558 lines (340 loc) · 22.8 KB

getting-started-wsl2_ja.md

File metadata and controls

558 lines (340 loc) · 22.8 KB

Windows 11 のｽﾀｯｸﾁｬﾝ環境構築マニュアル（WSL2）

ｽﾀｯｸﾁｬﾝはWindows11、MacOS、Linuxで開発ができます。MacOS、Linuxの場合は環境構築マニュアル（MacOS/Linux）を参照してください

Windows11上でｽﾀｯｸﾁｬﾝのプログラムを書き込む手順を説明します。 Moddableを使用したｽﾀｯｸﾁｬﾝの開発環境はUbuntuOSを想定しています。WSL2(Windows Subsystem for Linux 2)を使用することで、Windows環境上でUbuntuの環境を構築することができます。

Windows PowerShellとUbuntuの見分け方

この手順書では、Windows PowerShellとUbuntuの２種類のウインドウを扱います。インターフェースが類似しているため間違いやすいです。以下のようにコマンド入力欄に注目すると容易に見分けられます。

  • Windows PowerShell：コマンド入力欄の表示がPS C:\WINDOWS\system32>
  • Ubuntu：コマンド入力欄の末尾の表示が$

WSL2+Ubuntu22.04 LTSのインストール

WSL2とUbuntu 22.04 LTSをインストールします。

Caution

Ubuntu 24.04 LTSでも動作することを確認済みですが、アールティ版ｽﾀｯｸﾁｬﾝではUbuntu 22.04 LTS上での動作を推奨しています。


以下の3つの手順によって、Windows PowerShellを管理者権限で開いてください。

  1. Windowsキーを押す
  2. 検索欄に「windows powershell」と入力する
  3. Windows PowerShellのアイコンが出てくるので「管理者権限で開く」を選択してください。


WSL2のインストール

WSL2をインストールします。

開いたWindows PowerShell上に、以下のコマンドを入力し、実行してください。コマンドは画像の通り、PS C:\WINDOWS\system32>の後に続けて入力し、Enterキーで実行します。

PS C:\WINDOWS\system32> wsl --install

インストールが正常に終了したら、Windows PowerShellのウインドウを閉じます。その後、PCを再起動してください。


Ubuntu 22.04のインストール

Ubuntu 22.04をインストールします。

PCを再起動したら、再度Windows PowerShellを開き、以下のコマンドを入力して実行してください。

PS C:\WINDOWS\system32> wsl --install -d Ubuntu-22.04


この状態でしばらく待つと、Ubuntuで使用するユーザー名とパスワードの入力を求められますので任意の文字列を入力してください。

Note

ユーザー名では全角文字と大文字は使用できないため、小文字のみの半角文字の文字列で設定してください。また、パスワードは確認も合わせて2回の入力を要求されます。


ユーザー名とパスワードの設定が完了し、Installation successful!と表示されればインストールは成功です。ウインドウ右上の×アイコンをクリックしてWindows PowerShellを閉じてください。


Ubuntu 22.04の起動

以下の3つの手順によって、Ubuntuを開きます。（Ubuntuは管理者権限で起動せずに通常通りに起動してください）

  1. Windowsキーを押す
  2. 検索欄に「ubuntu 22」と入力する
  3. Ubuntu 22.04.x LTSのアイコンが出てくるので「開く」を選択する


Warning

本マニュアルでは Ubuntu 22.04 LTS を起動します。以下の画像のような、バージョン未指定のUbuntuには最新の安定版リリースが導入されるため、コマンドやツールの仕様が異なる場合があります。アールティ版ｽﾀｯｸﾁｬﾝはUbuntu 22.04上で動作確認済みですので、手順通りに実行するためにUbuntu 22.04 LTS環境をご用意ください。

Caution

　以降、本マニュアル内の「Ubuntu」の記述は、すべてUbuntu 22.04.x LTSを指します。



Ubuntuを起動後、末尾が$記号の文字列が表示されていればUbuntuのインストールと設定は完了です。 成功していれば、<設定したUbuntuのユーザー名>@...:~$表示されています。


Warning

Ubuntu起動時、root@"...:~#のように表示される場合、ユーザー作成の設定は失敗しています。 この状態に遭遇された際には本マニュアルの末尾の最初からやり直す場合の節を参照し、再度Ubuntuのインストールを行ってください。


Ubuntuのパッケージリストの更新と必要パッケージのインストール

Ubuntuにｽﾀｯｸﾁｬﾝの開発環境を構築します。 先程開いたUbuntuのウインドウ上で以下のコマンドを順番に入力してください。

コマンドは、$の後に続けて入力し、Enterキーで実行します。


Important

　UbuntuではWindows PowerShellと違い、キーボードによるコピー&ペーストはshiftキーも押す必要があります。

コピー：ctrl + shift + c

ペースト：ctrl + shift + v

特に、ctrl + cをUbuntu上で実行してしまうと、プロセス（現在実行しているコマンド・プログラム）の終了となりますのでご注意ください。


パッケージリストの更新

最新のパッケージのリストを更新します。

$ sudo apt update

venvのインストール

現在の python3 のバージョンに対応した venv パッケージをインストールします。 venv は Python の仮想環境を作成するためのツールです。

$ PYVER=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
$ sudo apt install -y python${PYVER}-venv

usbutilsのインストール

USBデバイスの情報を表示するコマンドを含むパッケージusbutilsをインストールします。

$ sudo apt install usbutils

dialoutグループの設定

USB接続デバイスに書き込めるようにするために、現在のユーザーに必要なアクセス権限を追加します。

sudo usermod -aG dialout $(whoami)

Node.jsとnpmのインストール

ｽﾀｯｸﾁｬﾝの開発にはNode.jsと、そのパッケージを管理するnpmという名前のソフトウェアを使います。

Ubuntuのパッケージマネージャー（apt）から直接インストールできるNode.jsのバージョンは古いため、VoltaというNode.jsのバージョン管理ツールを使って最新の安定版をインストールします。

Voltaのインストール

Node.jsとnpmを管理するツールVoltaをインストールします。

$ curl https://get.volta.sh | bash

インストールに成功するとsuccess: Setup complete. Open a new terminal to start using Volta!と表示され、新しいターミナルを再起動するように指示されます。

Ubuntuを再起動します。Ubuntuのウインドウ右上の×アイコンをクリックして閉じた後、Windows11のスタートメニューからUbuntuを選択して起動してください。


VoltaからNode.jsとnpmをインストール

Node.jsとnpmをインストールします。

$ volta install node@22.7.0

インストールしたNode.jsとnpmを確認

npmとNode.jsがインストール出来ているかを確認します。 以下の２つのコマンドをうち、それぞれ画像の通りに表示されれば完了です。

$ npm -v
$ node -v

Caution

実際に表示されるバージョンは、環境をセットアップした時期によって異なります。


ｽﾀｯｸﾁｬﾝのプログラムのインストール

ｽﾀｯｸﾁｬﾝのプログラムのダウンロード

ｽﾀｯｸﾁｬﾝのプログラムをダウンロードします。

$ git clone https://github.com/rt-net/stack-chan.git

ソフトウェアパッケージのインストール

ダウンロードしたｽﾀｯｸﾁｬﾝのfirmwareフォルダに移動し、必要なソフトウェアパッケージをインストールします。

cdコマンドで作業するフォルダを変更できます。

npm install でインストールを実行します。

$ cd stack-chan/firmware
$ npm install

Moddableのインストール

Moddableをインストールします。

コマンドnpm run setupによってスクリプトを実行します。スクリプトによって、自動でModdableのインストールが行われます。

以下に示す１つ目のコマンドの実行直後、Ubuntuに設定したパスワードの入力が要求されますので入力してください。 パスワード入力後、一定時間は同様のコマンドを実行してもパスワードは要求されません。 ２つ目のコマンドでは、再度パスワードが要求されない内に実行してください。 もし、何らかの理由で１つめのコマンド実行から時間がかかってしまった場合は１つ目のコマンドの実行からやり直してください。

$ sudo echo "Temporary SuperUser Grant"
$ npm run setup

M5Stack向けにModdableをセットアップ

以下のコマンドでModdableの環境をM5Stack向けにセットアップします。 npm run setup -- --device=esp32はスクリプトを実行し、自動で環境のセットアップを行います。

１つ目のコマンドを実行直後、Ubuntuに設定したパスワードの入力が要求されますので入力してください。 パスワード入力後、一定時間は同様のコマンドを実行してもパスワードは要求されません。 ２つ目のコマンドでは、このパスワードが要求されない内に実行してください。 もし、何らかの理由で１つめのコマンド実行から時間がかかってしまった場合は１つ目のコマンドの実行からやり直してください。

$ sudo echo "Temporary SuperUser Grant"
$ npm run setup -- --device=esp32

PSRAM無効化と環境変数のセットアップ

次のコマンドを実行して、PSRAM無効化の設定をします。

$ ./setting_scripts/unset_psram.sh

次のコマンドを実行し、Shellの設定ファイルにsource ~/.local/share/xs-dev-export.shを追加します。これにより、Shellの起動時に自動で環境変数が設定されるようになります。

$ ./setting_scripts/set_xs-dev_env.sh

構築した環境の確認

Ubuntuを再起動（Ubuntuのウインドウを閉じてから再度開く）し、以下のcdコマンドで作業フォルダを移動してください。

$ cd stack-chan/firmware

Moddableの環境確認

以下のコマンドでModdableの環境のテストをします。

$ npm run doctor

Moddableのバージョンがv4.9.5で、ESP32 IDF Directoryのパスが正しく表示されており、Supported target devicesがlin, esp32となっていれば成功です。

PSRAMの環境確認

以下のコマンドでM5Stack CoreS3のPSRAMの設定を確認します。

$ grep CONFIG_SPIRAM= $MODDABLE/build/devices/esp32/targets/m5stack_cores3/sdkconfig/sdkconfig.defaults

CONFIG_SPIRAM=nと表示されれば成功です。

ここまで完了次第、Ubuntuのウインドウを閉じてください。

PCのUSBポートに接続されたデバイスをWSL2上で認識できるようにする

ｽﾀｯｸﾁｬﾝにプログラムを書き込むには、USBケーブルでPCと接続する必要がありますが、WSL2上ではPCのUSBポートに接続したデバイスを読み取れません。 usbipd-winというツールを使用することでWSL2上でもPCのUSBポートに接続したデバイスを認識することができます。

usbipd-winのダウンロード

公式のダウンロードページから、最新版の.msi形式ファイルをダウンロードしてください。

usbipd-winのインストール

ダウンロードしてきたファイル（インストーラ）に従ってインストールしてください。インストールが完了したらPCを再起動してください。

ｽﾀｯｸﾁｬﾝをWSL2上から認識できるようにする

Windows PowerShellとUbuntuを両方起動します。Windows PowerShellは、管理者権限で実行します。

Important

これ以降の手順では、Windows PowerShellとUbuntuの両方を起動させ続けておく必要があります。


vhci-hcdモジュールのロード

Ubuntu側で以下のコマンドを実行し、vhci_hcdモジュールをロードします。実行の際はパスワードの入力を要求されます。

$ sudo modprobe vhci-hcd

Caution

modprobeコマンドは、Ubuntuを再起動するたびに実行する必要があります。


ｽﾀｯｸﾁｬﾝのBUSIDを確認する

ｽﾀｯｸﾁｬﾝのBUSIDを取得します。

Windows PowerShell側でusbipd listコマンドを実行し、USBポートに接続されたデバイスリスト出力します。

PS C:\WINDOWS\system32> usbipd list



以下の手順でｽﾀｯｸﾁｬﾝとPCを接続して起動します。

  1. ｽﾀｯｸﾁｬﾝとPCをUSBケーブルで接続します
  2. スライドスイッチを上側にスライドさせてｽﾀｯｸﾁｬﾝのバッテリー供給をONにします（同時にPCからバッテリーの充電も開始されます）
  3. 起動ボタンを押してｽﾀｯｸﾁｬﾝの電源をONにします（OFFにするときは6秒間長押しします）


Windows PowerShell側で、再度usbipd listコマンドを実行してUSBデバイスリスト出力します。

PS C:\WINDOWS\system32> usbipd list

今回のコマンドで新たに現れたBUSID（画像の場合では2-1）がｽﾀｯｸﾁｬﾝを指し示してます。

ｽﾀｯｸﾁｬﾝをbindする

ｽﾀｯｸﾁｬﾝをbindします。

Windows PowerShell側で、usbipd bindコマンドとusbipd listコマンドを実行します。

usbipd bindコマンドを実行する際は、以下に示すようにコマンドの<ｽﾀｯｸﾁｬﾝのBUSID>部分を自身のｽﾀｯｸﾁｬﾝのBUSIDと置き換えて実行します。 その後、usbipd listコマンドを実行して再度USBデバイスリスト出力してください。

PS C:\WINDOWS\system32> usbipd bind --busid <ｽﾀｯｸﾁｬﾝのBUSID>
PS C:\WINDOWS\system32> usbipd list

USBデバイスリスト上のｽﾀｯｸﾁｬﾝのBUSIDがSharedとなっていれば完了です。


ｽﾀｯｸﾁｬﾝをattachする

ｽﾀｯｸﾁｬﾝをattachします。

以下に示すように、ｽﾀｯｸﾁｬﾝのattachコマンドを実行した後、再度USBデバイスリスト出力してください。

（今回もbindのときと同様、<ｽﾀｯｸﾁｬﾝのBUSID>部分を自身のｽﾀｯｸﾁｬﾝのBUSID`と置き換えて実行します。）

PS C:\WINDOWS\system32> usbipd attach --wsl --busid <ｽﾀｯｸﾁｬﾝのBUSID>
PS C:\WINDOWS\system32> usbipd list

USBデバイスリスト上のｽﾀｯｸﾁｬﾝのBUSIDがAttachedとなっていれば完了です。

Caution

本手順（ｽﾀｯｸﾁｬﾝをattachする）は、ｽﾀｯｸﾁｬﾝとPCのUSBケーブルを再接続（挿し直し）したり、ｽﾀｯｸﾁｬﾝのリセットボタンを押すたびに再度実行する必要があります。


WSL2からｽﾀｯｸﾁｬﾝを認識できていることを確認する

WSL2からｽﾀｯｸﾁｬﾝを認識できるかを確認します。

Ubuntuでの作業に移ります。

lsusbコマンドで認識していることを確認します。 先程のPowerShell上でのｽﾀｯｸﾁｬﾝと同じ名称のデバイスが表示されています。 今回の例では、USB JTAG/serial debug unitです。

$ lsusb

プログラムのビルドと書き込み

ダウンロードしたｽﾀｯｸﾁｬﾝのfirmwareに移動し、プログラムのビルド・書き込みます。ビルドを行うことで、プログラムをM5Stackが実行できる形式に変換できます。ビルドしたプログラムをM5Stackに書き込めれば、ｽﾀｯｸﾁｬﾝを動かす手順は完了です。

先程の操作からUbuntuのウインドウを開いた状態であれば、一度再起動（Ubuntuのウインドウを閉じてから再度開く）してください。

cd stack-chan/firmwareで作業フォルダを移動し、npm run build --target=esp32/m5stack_cores3コマンドを実行してビルドします。

次に、npm run deploy --target=esp32/m5stack_cores3を実行すればビルドしたプログラムをｽﾀｯｸﾁｬﾝに書き込めます。

$ cd stack-chan/firmware
$ npm run build --target=esp32/m5stack_cores3
$ npm run deploy --target=esp32/m5stack_cores3



以下のように書き込みが完了次第、リセットボタンを押下してください。



リセットボタンの位置

リセットボタンを押下した後にｽﾀｯｸﾁｬﾝに顔が表示されていれば書き込み完了です。


Caution

リセットボタンを押下した場合、再度プログラムを書き込むためには、ｽﾀｯｸﾁｬﾝをattachする 手順も再度実行する必要があります。


最初からやり直す場合

マニュアルの手順通りに進められなかったり、エラーが出力されてしまった場合は、エラー内容に従ったり調べたりすることで解決に繋がる場合があります。 ですが、Ubuntuを一旦アンインストールし、きれいな環境で最初から実行するという手段もあります。

管理者権限で開いたWindows PowerShell上で以下のコマンドを実行することで現在のUbuntuを削除することができます。

PS C:\WINDOWS\system32>  wsl --unregister Ubuntu-22.04

上記のコマンドでUbuntuを削除した後、Windows11のスタートメニューから、再度Ubuntuを選択します。 自動でUbuntuのインストールが開始され、しばらく待つとインストールが完了します。

しばらくするとUbuntuインストール後の時点と同じ状態になりますので、再度構築を開始してください。

よくある質問

リリースファイルの有効期限切れエラー

WSL2とPCの設定時間がずれていると、sudo apt updateコマンド実行の際に以下の画像のようにセキュリティ上のエラーが起きます。

sudo apt updateコマンドの実行が完了していない場合、これ以降の手順でも失敗するため、正しく同期していることを確認してください。

$ sudo apt update
[sudo] password for ubuntu:
Get:1 http://security.ubuntu.com/ubuntu jammy-security InRelease [110 kB]
Hit:2 http://archive.ubuntu.com/ubuntu jammy InRelease
Get:3 http://archive.ubuntu.com/ubuntu jammy-updates InRelease [119 kB]
Get:4 http://archive.ubuntu.com/ubuntu jammy-backports InRelease [109 kB]
Reading package lists... Done
E: Release file for http://security.ubuntu.com/ubuntu/dists/jammy-security/InRelease is not valid yet (invalid for another 8h 24min 40s). Updates for this repository will not be applied.
E: Release file for http://archive.ubuntu.com/ubuntu/dists/jammy-updates/InRelease is not valid yet (invalid for another 8h 25min 52s). Updates for this repository will not be applied.
E: Release file for http://archive.ubuntu.com/ubuntu/dists/jammy-backports/InRelease is not valid yet (invalid for another 6h 47min 42s). Updates for this repository will not be applied.